npm package: @jadermme/orus-core
Description: ORUS Core Framework - Universal framework for 6 Pillars assessment, domain-agnostic
Author: Jader Mendonça
Latest version: 1.0.0

# @orus/core

> Universal framework for 6 Pillars assessment methodology - 100% domain-agnostic

[![npm version](https://img.shields.io/npm/v/@orus/core.svg)](https://www.npmjs.com/package/@orus/core)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.6+-blue.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Test Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)](./coverage)

## Overview

**ORUS Core** is a universal framework that powers the 6 Pillars assessment methodology. It provides a stable, extensible foundation that can be used across multiple verticals (Finance, Marketing, Career, Health, Creators) without modification.

### Why ORUS Core?

- 🎯 **Single source of truth** - One framework for all assessment domains
- 🔧 **Configuration-driven** - Customize via config, not code modification
- 📊 **Data-driven decisions** - Scoring, prioritization, and validation built-in
- 🧪 **Battle-tested** - 97% test coverage, pure functions, type-safe
- 🚀 **Production-ready** - Built for 5-10 year stability

## Key Principles

- ✅ **100% domain-agnostic** - Zero references to specific domains
- ✅ **Zero framework dependencies** - Works in any JavaScript environment
- ✅ **Pure functions** - Deterministic, testable, side-effect free
- ✅ **Extensible via configuration** - Override defaults without forking
- ✅ **Type-safe** - Full TypeScript support with strict mode
- ✅ **Stable API** - Built to last 5-10 years

## Installation

```bash
npm install @orus/core
# or
pnpm add @orus/core
# or
yarn add @orus/core
```

## Quick Start

```typescript
import {
  PillarId,
  createOrusCore,
  prioritizePillars
} from '@orus/core';

// Create configured instance
const orus = createOrusCore({
  pillarLabels: {
    [PillarId.PILLAR_1]: "Financial Organization",
    [PillarId.PILLAR_2]: "Protection & Emergency",
    // ... other labels
  },
  vertical: {
    name: "ORUS Finance",
    version: "1.0.0"
  }
});

// Use the framework
const prioritization = prioritizePillars({ assessment });
console.log('Top priority:', prioritization.ranking[0]);
```

## Core Modules

### 📊 Scoring Engine

Pure functions for score manipulation and inference:

```typescript
import {
  clampScore,
  inferStatusFromScore,
  normalizeScoreFromStatus,
  adjustScoreByConfidence,
  calculateScoreDelta
} from '@orus/core';

// Ensure score is in valid range (0-10)
const safe = clampScore(15); // => 10

// Infer status from numeric score
const status = inferStatusFromScore(3.5); // => "critical"

// Convert status to representative score
const score = normalizeScoreFromStatus("healthy"); // => 8.5

// Adjust for confidence level
const adjusted = adjustScoreByConfidence(7.0, "low");
// => { adjustedScore: 6.1, confidenceFactor: 0.7 }
```

### 🎯 Prioritization Engine

Intelligent pillar ranking based on multiple factors:

```typescript
import { prioritizePillars, getTopPriorities } from '@orus/core';

// Rank pillars by urgency
const result = prioritizePillars({
  assessment,
  strategy: 'worst_first', // or 'best_first', 'impact_first'
  weights: {
    status: 0.40,      // Current health state
    score: 0.30,       // Numeric score
    trend: 0.20,       // Direction of change
    confidence: 0.10   // Data reliability
  }
});

// Get top 3 priorities
const top3 = getTopPriorities(result, 3);
```

### 🔄 Mode Logic

Handles assessment mode transitions and hybrid calculations:

```typescript
import {
  resolveHybridScore,
  canTransitionMode,
  suggestOptimalMode
} from '@orus/core';

// Combine subjective and objective scores
const hybrid = resolveHybridScore({
  subjectiveScore: 5.0,
  objectiveScore: 7.5,
  strategy: 'objective_priority' // 70% objective, 30% subjective
});

// Validate mode transition
const validation = canTransitionMode(
  { from: 'subjective', to: 'objective' },
  0.75 // data completeness
);

// Get recommended mode based on data
const suggestion = suggestOptimalMode(0.6);
// => { mode: 'hybrid', reason: '...', confidence: 'medium' }
```

### ✅ Validation & Completeness

Data integrity and completeness tracking:

```typescript
import {
  validatePillarAssessment,
  validateSixPillarsAssessment,
  calculatePillarCompleteness,
  calculateAssessmentCompleteness,
  isReadyForMode
} from '@orus/core';

// Validate pillar data
const validation = validatePillarAssessment(pillar, true); // strict mode
if (!validation.isValid) {
  console.error('Errors:', validation.errors);
}

// Calculate data completeness
const completeness = calculateAssessmentCompleteness(assessment);
console.log(`Overall: ${completeness.overall * 100}%`);
console.log(`Suggestions:`, completeness.suggestions);

// Check mode readiness
if (isReadyForMode(assessment, 'objective')) {
  // Sufficient data for objective mode
}
```

### ⚙️ Configuration System

Centralized, type-safe configuration:

```typescript
import { createOrusCore } from '@orus/core';

const orus = createOrusCore({
  pillarLabels: {
    [PillarId.PILLAR_1]: "Your Label",
    // ... 6 labels required
  },
  statusThresholds: {
    critical: [0, 4],
    attention: [4.1, 7],
    healthy: [7.1, 10]
  },
  prioritizationWeights: {
    status: 0.5,
    score: 0.3,
    trend: 0.15,
    confidence: 0.05
  },
  verticalSchema: {
    pillars: { /* field schemas */ },
    minCompletenessForObjective: 0.8,
    minCompletenessForHybrid: 0.5
  },
  debug: false
});

// Use instance methods
const label = orus.getPillarLabel(PillarId.PILLAR_1);
const thresholds = orus.getStatusThresholds();
```

## Core Concepts

### The 6 Universal Pillars

ORUS Core defines 6 universal pillars with fixed IDs:

- `PILLAR_1` through `PILLAR_6`

**Important:** Core uses neutral labels ("Pillar 1", etc.) for debugging. Each vertical/shell **MUST** override with domain-specific labels.

### Assessment Modes

| Mode | Description | Confidence | Use Case |
|------|-------------|-----------|----------|
| `subjective` | User perception | Low | Quick assessment, no data |
| `objective` | Data-driven | High | Full data collection |
| `hybrid` | Combined approach | Medium | Partial data + user input |

### Status Classification

| Status | Score Range | Meaning |
|--------|-------------|---------|
| `critical` | 0 - 3.9 | Immediate attention required |
| `attention` | 4.0 - 6.9 | Needs improvement |
| `healthy` | 7.0 - 10.0 | Maintain and optimize |

## What's NOT in the Core

ORUS Core is intentionally minimal. It does NOT include:

- ❌ Domain-specific logic (financial calculations, marketing metrics, etc.)
- ❌ Assessment questions or questionnaires
- ❌ UI components or React hooks
- ❌ Persistence layer (databases, localStorage, APIs)
- ❌ Authentication or authorization
- ❌ Routing or navigation
- ❌ Branding, texts, or microcopy

These belong in:
- **Verticals** (e.g., `@orus/finance`) - Domain-specific logic
- **Shells** (e.g., Convexa360) - Branding and UX implementation

## Architecture

```
┌─────────────────────────┐
│    @orus/core           │  Universal Framework
│  (domain-agnostic)      │  • Types & Interfaces
└───────────┬─────────────┘  • Scoring & Prioritization
            │                • Validation & Completeness
            ↓ implements     • Configuration System
┌─────────────────────────┐
│  Vertical Package       │  Domain Logic
│  (e.g., @orus/finance)  │  • Pillar labels
└───────────┬─────────────┘  • Domain engines
            │                • Field schemas
            ↓ customizes
┌─────────────────────────┐
│  Shell Application      │  Branding & UX
│  (e.g., Convexa360)     │  • UI components
└─────────────────────────┘  • User flows
                              • Persistence
```

## TypeScript Support

ORUS Core is written in TypeScript with strict mode enabled. All exports are fully typed:

```typescript
import type {
  PillarId,
  PillarStatus,
  PillarMode,
  PillarAssessment,
  SixPillarsAssessment,
  PrioritizationResult,
  ValidationResult,
  OrusCoreConfig
} from '@orus/core';
```

## Testing

```bash
# Run tests
pnpm test

# Run with coverage
pnpm test:coverage

# Watch mode
pnpm test:watch
```

Current coverage: **97% lines, 100% functions, 92% branches**

## Contributing

ORUS Core is designed for long-term stability. Breaking changes are avoided. Contributions should:

1. Maintain 100% domain-agnosticism
2. Use pure functions (no side effects)
3. Include comprehensive tests (≥95% coverage)
4. Follow TypeScript strict mode
5. Update documentation

## License

MIT © Jader Mendonça

---

**Status:** v1.0.0 - Production Ready
**Schema Version:** 1
**Node:** >=18.0.0

Built with ❤️ for sustainable, scalable assessment frameworks.