@cleocode/core 2026.3.44 → 2026.3.46

package/schemas/spec-index.schema.json

@@ -0,0 +1,196 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "schemaVersion": "1.0.0",
+  "$id": "https://cleo-dev.com/schemas/v1/spec-index.schema.json",
+  "title": "Claude-TODO Specification Index",
+  "description": "Schema for the authoritative specification index. LLM-agent-first design: structured, queryable, schema-validated.",
+  "type": "object",
+  "required": ["$schema", "_meta", "authorities", "specs"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://cleo-dev.com/schemas/v1/spec-index.schema.json"
+    },
+    "_meta": {
+      "type": "object",
+      "description": "Index metadata for version tracking and integrity",
+      "required": ["version", "lastUpdated", "totalSpecs", "totalReports"],
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Semantic version of the index format"
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO date of last index update"
+        },
+        "totalSpecs": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of specification documents"
+        },
+        "totalReports": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Count of implementation reports"
+        },
+        "checksum": {
+          "type": "string",
+          "description": "Optional SHA256 for integrity verification"
+        }
+      }
+    },
+    "authorities": {
+      "type": "object",
+      "description": "Domain to authoritative specification mapping. Query: 'What is the authoritative source for X?'",
+      "additionalProperties": {
+        "type": "string",
+        "description": "Filename of authoritative spec for this domain"
+      }
+    },
+    "specs": {
+      "type": "array",
+      "description": "All specification documents with metadata",
+      "items": {
+        "$ref": "#/definitions/specEntry"
+      }
+    },
+    "reports": {
+      "type": "array",
+      "description": "All implementation reports with progress tracking",
+      "items": {
+        "$ref": "#/definitions/reportEntry"
+      }
+    },
+    "recentChanges": {
+      "type": "array",
+      "description": "Last 20 changes for change tracking",
+      "maxItems": 20,
+      "items": {
+        "$ref": "#/definitions/changeEntry"
+      }
+    }
+  },
+  "definitions": {
+    "specEntry": {
+      "type": "object",
+      "required": ["file", "version", "status", "type", "domain", "synopsis", "lastUpdated"],
+      "properties": {
+        "file": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+\\.(md|json)$",
+          "description": "Filename (not path)"
+        },
+        "version": {
+          "type": "string",
+          "description": "Semantic version or version string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["DRAFT", "APPROVED", "ACTIVE", "IMMUTABLE", "DEPRECATED", "PLANNING", "IMPLEMENTED"],
+          "description": "Document lifecycle status"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["SPEC", "GUIDELINES", "PLAN"],
+          "description": "Document type classification"
+        },
+        "domain": {
+          "type": "string",
+          "description": "Primary domain this spec covers"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["core-system", "feature", "design-philosophy", "integration", "process"],
+          "description": "Organizational category"
+        },
+        "synopsis": {
+          "type": "string",
+          "maxLength": 200,
+          "description": "1-2 sentence purpose summary"
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date",
+          "description": "ISO date of last document update"
+        },
+        "dependsOn": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Specs this document depends on (filenames)"
+        },
+        "dependedOnBy": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Specs that depend on this document (filenames)"
+        },
+        "implementationReport": {
+          "type": "string",
+          "description": "Filename of associated implementation report"
+        },
+        "isAuthoritativeFor": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Domains this spec is authoritative for"
+        }
+      }
+    },
+    "reportEntry": {
+      "type": "object",
+      "required": ["file", "relatedSpec", "progress", "lastUpdated"],
+      "properties": {
+        "file": {
+          "type": "string",
+          "pattern": "^[A-Z0-9-]+-IMPLEMENTATION-REPORT\\.md$"
+        },
+        "relatedSpec": {
+          "type": "string",
+          "description": "Filename of the spec this tracks"
+        },
+        "progress": {
+          "type": "string",
+          "description": "Progress indicator (e.g., '85%', '16/18', 'Varies')"
+        },
+        "phase": {
+          "type": "string",
+          "description": "Current implementation phase"
+        },
+        "lastUpdated": {
+          "type": "string",
+          "format": "date"
+        },
+        "notes": {
+          "type": "string",
+          "maxLength": 100,
+          "description": "Brief status note"
+        }
+      }
+    },
+    "changeEntry": {
+      "type": "object",
+      "required": ["date", "file", "changeType", "description"],
+      "properties": {
+        "date": {
+          "type": "string",
+          "format": "date"
+        },
+        "file": {
+          "type": "string"
+        },
+        "changeType": {
+          "type": "string",
+          "enum": ["Created", "Updated", "StatusChange", "Deprecated"]
+        },
+        "version": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 100
+        }
+      }
+    }
+  }
+}

package/schemas/system-flow-atlas.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CLEO System Flow Atlas Structure",
+  "description": "Validates that a System Flow Atlas document contains all required sections",
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "const": "CLEO System Flow Atlas",
+      "description": "Document title"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d{4}\\.\\d{1,2}\\.\\d{1,2}$",
+      "description": "CalVer version (YYYY.M.D)"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["DRAFT", "REVIEW", "APPROVED", "STABLE", "SUPERSEDED", "ARCHIVED"],
+      "description": "Document lifecycle status"
+    },
+    "sections": {
+      "type": "object",
+      "description": "Required sections in the atlas document",
+      "properties": {
+        "purpose": {
+          "type": "boolean",
+          "description": "Section 1: Purpose exists"
+        },
+        "systemDomainMapping": {
+          "type": "boolean",
+          "description": "Section 2: Four systems mapped to 10 domains"
+        },
+        "requestFlow": {
+          "type": "boolean",
+          "description": "Section 3: End-to-end request flow diagram"
+        },
+        "domainInteractionGraph": {
+          "type": "boolean",
+          "description": "Section 4: Domain interaction graph"
+        },
+        "dataStores": {
+          "type": "boolean",
+          "description": "Section 5: Data stores and ownership boundaries"
+        },
+        "distillationFlow": {
+          "type": "boolean",
+          "description": "Section 6: LOOM distillation flow"
+        },
+        "flowExamples": {
+          "type": "boolean",
+          "description": "Section 7: Query/mutate flow examples"
+        },
+        "progressiveDisclosure": {
+          "type": "boolean",
+          "description": "Section 8: Progressive disclosure in practice"
+        },
+        "failureRecovery": {
+          "type": "boolean",
+          "description": "Section 9: Failure and recovery paths"
+        },
+        "observability": {
+          "type": "boolean",
+          "description": "Section 10: Observability and audit trails"
+        },
+        "invariants": {
+          "type": "boolean",
+          "description": "Section 11: Canonical invariants"
+        },
+        "glossary": {
+          "type": "boolean",
+          "description": "Section 12: Glossary"
+        }
+      },
+      "required": [
+        "purpose",
+        "systemDomainMapping",
+        "requestFlow",
+        "domainInteractionGraph",
+        "dataStores",
+        "distillationFlow",
+        "flowExamples",
+        "progressiveDisclosure",
+        "failureRecovery",
+        "observability",
+        "invariants",
+        "glossary"
+      ]
+    },
+    "domains": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "tasks",
+          "session",
+          "memory",
+          "check",
+          "pipeline",
+          "orchestrate",
+          "tools",
+          "admin",
+          "nexus",
+          "sticky"
+        ]
+      },
+      "minItems": 10,
+      "maxItems": 10,
+      "uniqueItems": true,
+      "description": "All 10 canonical domains MUST be referenced"
+    },
+    "systems": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["BRAIN", "LOOM", "NEXUS", "LAFS"]
+      },
+      "minItems": 4,
+      "maxItems": 4,
+      "uniqueItems": true,
+      "description": "All 4 conceptual systems MUST be documented"
+    }
+  },
+  "required": ["title", "version", "status", "sections", "domains", "systems"]
+}

package/src/__tests__/injection-chain.test.ts

@@ -3,9 +3,10 @@
  *
  * Verifies the new AGENTS.md hub injection architecture:
  * 1. Provider files (CLAUDE.md, GEMINI.md) reference @AGENTS.md
- * 2. AGENTS.md references @~/.cleo/templates/CLEO-INJECTION.md
- * 3. No references to @.cleo/templates/AGENT-INJECTION.md anywhere
- * 4. No CLEO:START markers anywhere (CAAMP uses CAAMP:START/END)
+ * 2. Project AGENTS.md references @~/.agents/AGENTS.md (global hub)
+ * 3. Global ~/.agents/AGENTS.md references @~/.cleo/templates/CLEO-INJECTION.md
+ * 4. No references to @.cleo/templates/AGENT-INJECTION.md anywhere
+ * 5. No CLEO:START markers anywhere (CAAMP uses CAAMP:START/END)
  *
  * Since CAAMP functions depend on actual provider installations,
  * they are mocked via vi.mock to isolate the init logic.
@@ -159,13 +160,13 @@ describe('E2E: injection chain validation (T4694)', () => {
     expect(geminiContent).toContain('@AGENTS.md');
   });
 
-  it('AGENTS.md references @~/.cleo/templates/CLEO-INJECTION.md', async () => {
+  it('AGENTS.md references @~/.agents/AGENTS.md (global hub)', async () => {
     await initProject({ name: 'chain-test' });
 
     const agentsPath = join(testDir, 'AGENTS.md');
     expect(existsSync(agentsPath)).toBe(true);
     const agentsContent = await readFile(agentsPath, 'utf-8');
-    expect(agentsContent).toContain('@~/.cleo/templates/CLEO-INJECTION.md');
+    expect(agentsContent).toContain('@~/.agents/AGENTS.md');
   });
 
   it('no references to @.cleo/templates/AGENT-INJECTION.md in generated files', async () => {
@@ -216,7 +217,7 @@ describe('E2E: injection chain validation (T4694)', () => {
     expect(createdStr).toContain('AGENTS.md');
   });
 
-  it('injection chain: provider -> AGENTS.md -> CLEO-INJECTION.md', async () => {
+  it('injection chain: provider -> AGENTS.md -> ~/.agents/AGENTS.md -> CLEO-INJECTION.md', async () => {
     await initProject({ name: 'chain-test' });
 
     // Verify the full chain:
@@ -224,9 +225,9 @@ describe('E2E: injection chain validation (T4694)', () => {
     const claudeContent = await readFile(join(testDir, 'CLAUDE.md'), 'utf-8');
     expect(claudeContent).toContain('@AGENTS.md');
 
-    // AGENTS.md -> @~/.cleo/templates/CLEO-INJECTION.md (via inject)
+    // AGENTS.md -> @~/.agents/AGENTS.md (project hub references global hub)
     const agentsContent = await readFile(join(testDir, 'AGENTS.md'), 'utf-8');
-    expect(agentsContent).toContain('@~/.cleo/templates/CLEO-INJECTION.md');
+    expect(agentsContent).toContain('@~/.agents/AGENTS.md');
 
     // Neither should reference the old AGENT-INJECTION.md pattern
     expect(claudeContent).not.toContain('AGENT-INJECTION.md');
@@ -241,11 +242,11 @@ describe('E2E: injection chain validation (T4694)', () => {
 
     await initProject({ name: 'no-provider-test' });
 
-    // AGENTS.md should still exist and reference CLEO-INJECTION.md
+    // AGENTS.md should still exist and reference the global hub
     const agentsPath = join(testDir, 'AGENTS.md');
     expect(existsSync(agentsPath)).toBe(true);
     const agentsContent = await readFile(agentsPath, 'utf-8');
-    expect(agentsContent).toContain('@~/.cleo/templates/CLEO-INJECTION.md');
+    expect(agentsContent).toContain('@~/.agents/AGENTS.md');
   });
 
   it('updateDocs refreshes injection without full reinit', async () => {

package/src/__tests__/injection-mvi-tiers.test.ts

@@ -17,8 +17,10 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 
 const thisFile = fileURLToPath(import.meta.url);
-const monorepoRoot = resolve(dirname(thisFile), '..', '..', '..', '..');
-const injectionPath = join(monorepoRoot, 'templates', 'CLEO-INJECTION.md');
+// Template moved to packages/core/templates/ (was at monorepo root templates/)
+// thisFile is at packages/core/src/__tests__/, go up two levels to reach packages/core/
+const corePackageRoot = resolve(dirname(thisFile), '..', '..');
+const injectionPath = join(corePackageRoot, 'templates', 'CLEO-INJECTION.md');
 
 const templateExists = existsSync(injectionPath);
 

package/src/admin/import-tasks.ts

@@ -3,13 +3,14 @@
  *
  * Extracted from CLI import-tasks command for dispatch layer access.
  *
- * @task T5323, T5328
+ * @task T5323, T5328, T046
  * @epic T4545
  */
 
 import { constants as fsConstants } from 'node:fs';
 import { access, readFile } from 'node:fs/promises';
 import type { Task, TaskStatus } from '@cleocode/contracts';
+import type { ImportFromPackageOptions, ImportFromPackageResult } from '../nexus/transfer-types.js';
 import { getAccessor } from '../store/data-accessor.js';
 import type { ExportPackage } from '../store/export.js';
 import {
@@ -74,25 +75,13 @@ export interface ImportTasksResult {
 }
 
 /**
- * Import tasks from a cross-project export package with ID remapping.
+ * Import tasks from an in-memory ExportPackage with ID remapping.
+ * Core logic extracted from importTasksPackage for reuse by transfer engine.
  */
-export async function importTasksPackage(params: ImportTasksParams): Promise<ImportTasksResult> {
-  const { file } = params;
-
-  try {
-    await access(file, fsConstants.R_OK);
-  } catch {
-    throw new Error(`Export file not found: ${file}`);
-  }
-
-  const content = await readFile(file, 'utf-8');
-  let exportPkg: ExportPackage;
-  try {
-    exportPkg = JSON.parse(content) as ExportPackage;
-  } catch {
-    throw new Error(`Invalid JSON in: ${file}`);
-  }
-
+export async function importFromPackage(
+  exportPkg: ExportPackage,
+  options: ImportFromPackageOptions = {},
+): Promise<ImportFromPackageResult> {
   if (exportPkg._meta?.format !== 'cleo-export') {
     throw new Error(
       `Invalid export format (expected 'cleo-export', got '${exportPkg._meta?.format}')`,
@@ -103,17 +92,17 @@ export async function importTasksPackage(params: ImportTasksParams): Promise<Imp
     throw new Error('Export package contains no tasks');
   }
 
-  const accessor = await getAccessor(params.cwd);
+  const accessor = await getAccessor(options.cwd);
   const { tasks: existingTasks } = await accessor.queryTasks({});
 
-  const onConflict: OnConflict = params.onConflict ?? 'fail';
-  const onMissingDep: OnMissingDep = params.onMissingDep ?? 'strip';
-  const force = params.force ?? false;
-  const parentId = params.parent;
-  const phaseOverride = params.phase;
-  const addLabel = params.addLabel;
-  const resetStatus = params.resetStatus;
-  const addProvenance = params.provenance !== false;
+  const onConflict: OnConflict = options.onConflict ?? 'fail';
+  const onMissingDep: OnMissingDep = options.onMissingDep === 'fail' ? 'fail' : 'strip';
+  const force = options.force ?? false;
+  const parentId = options.parent;
+  const phaseOverride = options.phase;
+  const addLabel = options.addLabel;
+  const resetStatus = options.resetStatus;
+  const addProvenance = options.provenance !== false;
 
   if (parentId) {
     const parentExists = existingTasks.some((t) => t.id === parentId);
@@ -195,7 +184,7 @@ export async function importTasksPackage(params: ImportTasksParams): Promise<Imp
     existingIds.add(remapped.id);
   }
 
-  if (params.dryRun) {
+  if (options.dryRun) {
     return {
       imported: transformed.length,
       skipped: skipped.length,
@@ -217,3 +206,38 @@ export async function importTasksPackage(params: ImportTasksParams): Promise<Imp
     idRemap: idRemapJson,
   };
 }
+
+/**
+ * Import tasks from a cross-project export package file with ID remapping.
+ * Thin wrapper around importFromPackage that handles file I/O.
+ */
+export async function importTasksPackage(params: ImportTasksParams): Promise<ImportTasksResult> {
+  const { file } = params;
+
+  try {
+    await access(file, fsConstants.R_OK);
+  } catch {
+    throw new Error(`Export file not found: ${file}`);
+  }
+
+  const content = await readFile(file, 'utf-8');
+  let exportPkg: ExportPackage;
+  try {
+    exportPkg = JSON.parse(content) as ExportPackage;
+  } catch {
+    throw new Error(`Invalid JSON in: ${file}`);
+  }
+
+  return importFromPackage(exportPkg, {
+    cwd: params.cwd,
+    dryRun: params.dryRun,
+    parent: params.parent,
+    phase: params.phase,
+    addLabel: params.addLabel,
+    provenance: params.provenance,
+    resetStatus: params.resetStatus,
+    onConflict: params.onConflict,
+    onMissingDep: params.onMissingDep === 'placeholder' ? 'strip' : params.onMissingDep,
+    force: params.force,
+  });
+}

package/src/agents/__tests__/capacity.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tests for capacity tracking and load balancing.
+ *
+ * @module agents/__tests__/capacity.test
+ */
+export {};
+//# sourceMappingURL=capacity.test.d.ts.map

package/src/agents/__tests__/capacity.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capacity.test.d.ts","sourceRoot":"","sources":["capacity.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}