crewly 1.13.0 → 1.14.0

package/dist/cli/backend/src/types/v2/key-result.types.js

@@ -0,0 +1,264 @@
+/**
+ * Key Result Types for OKR Closed-Loop Execution
+ *
+ * Defines structured, measurable Key Results that attach to Missions.
+ * Each KR tracks a quantifiable target with baseline/current/target values,
+ * measurement history, and linked WorkItems.
+ *
+ * @module types/v2/key-result
+ */
+import { randomUUID } from 'crypto';
+/** All valid KR metric types. */
+export const KR_METRIC_TYPES = [
+    'number',
+    'percentage',
+    'boolean',
+    'currency',
+];
+/** All valid KR statuses. */
+export const KR_STATUSES = [
+    'not_started',
+    'on_track',
+    'at_risk',
+    'off_track',
+    'achieved',
+];
+/** All valid measurement sources. */
+export const KR_MEASUREMENT_SOURCES = [
+    'manual',
+    'task_completion',
+    'skill_output',
+];
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+/**
+ * Check if a value is a valid KRMetricType.
+ */
+export function isValidKRMetricType(value) {
+    return typeof value === 'string' && KR_METRIC_TYPES.includes(value);
+}
+/**
+ * Check if a value is a valid KRStatus.
+ */
+export function isValidKRStatus(value) {
+    return typeof value === 'string' && KR_STATUSES.includes(value);
+}
+/**
+ * Check if a value is a valid KRMeasurementSource.
+ */
+export function isValidKRMeasurementSource(value) {
+    return typeof value === 'string' && KR_MEASUREMENT_SOURCES.includes(value);
+}
+/**
+ * Validate a CreateKeyResultInput.
+ *
+ * @returns Array of validation error messages (empty if valid)
+ */
+export function validateCreateKeyResultInput(input) {
+    const errors = [];
+    if (!input || typeof input !== 'object')
+        return ['Input must be an object'];
+    const obj = input;
+    if (!obj.missionId || typeof obj.missionId !== 'string')
+        errors.push('missionId is required');
+    if (!obj.title || typeof obj.title !== 'string')
+        errors.push('title is required');
+    if (!isValidKRMetricType(obj.metricType))
+        errors.push(`metricType must be one of: ${KR_METRIC_TYPES.join(', ')}`);
+    if (typeof obj.baseline !== 'number')
+        errors.push('baseline must be a number');
+    if (typeof obj.target !== 'number')
+        errors.push('target must be a number');
+    if (!obj.unit || typeof obj.unit !== 'string')
+        errors.push('unit is required');
+    if (obj.baseline === obj.target)
+        errors.push('baseline and target must be different');
+    if (obj.measurementSource !== undefined && !isValidKRMeasurementSource(obj.measurementSource)) {
+        errors.push(`measurementSource must be one of: ${KR_MEASUREMENT_SOURCES.join(', ')}`);
+    }
+    return errors;
+}
+/**
+ * Type guard for KeyResult.
+ */
+export function isKeyResult(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return (typeof obj.id === 'string' &&
+        typeof obj.missionId === 'string' &&
+        typeof obj.title === 'string' &&
+        isValidKRMetricType(obj.metricType) &&
+        typeof obj.baseline === 'number' &&
+        typeof obj.target === 'number' &&
+        typeof obj.current === 'number' &&
+        typeof obj.unit === 'string' &&
+        isValidKRStatus(obj.status) &&
+        Array.isArray(obj.linkedWorkItemIds) &&
+        Array.isArray(obj.measurements));
+}
+// ---------------------------------------------------------------------------
+// Factory & Computation
+// ---------------------------------------------------------------------------
+/** Maximum measurement history entries to retain per KR. */
+export const MAX_MEASUREMENT_HISTORY = 50;
+/**
+ * Compute the progress percentage for a Key Result.
+ *
+ * Works for both "higher is better" (target > baseline) and
+ * "lower is better" (target < baseline) metrics.
+ *
+ * @returns Progress as 0-100 (clamped)
+ */
+export function computeKRProgress(kr) {
+    const range = kr.target - kr.baseline;
+    if (range === 0)
+        return 100;
+    const progress = ((kr.current - kr.baseline) / range) * 100;
+    return Math.max(0, Math.min(100, progress));
+}
+/**
+ * Progress thresholds (0-100) that delimit the KR status bands. A progress at or
+ * above a threshold maps to the associated status (checked high → low).
+ */
+export const KR_STATUS_THRESHOLDS = {
+    /** At/above this progress the KR is fully achieved. */
+    ACHIEVED: 100,
+    /** At/above this progress the KR is healthy / on track. */
+    ON_TRACK: 50,
+    /** At/above this progress the KR is at risk (but not off track). */
+    AT_RISK: 25,
+};
+/**
+ * Derive KR status from progress percentage.
+ *
+ * - achieved: progress >= 100%
+ * - on_track: progress >= 50%
+ * - at_risk: progress >= 25%
+ * - off_track: progress > 0%
+ * - not_started: progress === 0% and current === baseline
+ */
+export function deriveKRStatus(progress, current, baseline) {
+    if (progress >= KR_STATUS_THRESHOLDS.ACHIEVED)
+        return 'achieved';
+    if (current === baseline)
+        return 'not_started';
+    if (progress >= KR_STATUS_THRESHOLDS.ON_TRACK)
+        return 'on_track';
+    if (progress >= KR_STATUS_THRESHOLDS.AT_RISK)
+        return 'at_risk';
+    return 'off_track';
+}
+/**
+ * Map a cascade child's rolled-up progress to a single synthetic KR status used
+ * to fold the child into its parent's roll-up recommendation.
+ *
+ * Unlike {@link deriveKRStatus}, this mapper deliberately has NO
+ * `current === baseline` short-circuit: a child stalled at `0` progress is a
+ * genuine "in trouble" signal (`off_track`), NOT `not_started`. Treating an
+ * all-children-at-zero parent as `not_started` would suppress the
+ * escalate/replan recommendation the cascade is meant to surface (spec §4.2).
+ *
+ * Banding mirrors {@link deriveKRStatus}:
+ * - achieved: progress >= 100%
+ * - on_track: progress >= 50%
+ * - at_risk: progress >= 25%
+ * - off_track: progress < 25% (including exactly 0%)
+ *
+ * @param rolledUpProgress - The child's rolled-up progress (0-100)
+ * @returns The synthetic {@link KRStatus} for the child
+ *
+ * @example
+ * ```ts
+ * deriveCascadeChildStatus(0);  // 'off_track' (a stalled child escalates)
+ * deriveCascadeChildStatus(75); // 'on_track'
+ * ```
+ */
+export function deriveCascadeChildStatus(rolledUpProgress) {
+    if (rolledUpProgress >= KR_STATUS_THRESHOLDS.ACHIEVED)
+        return 'achieved';
+    if (rolledUpProgress >= KR_STATUS_THRESHOLDS.ON_TRACK)
+        return 'on_track';
+    if (rolledUpProgress >= KR_STATUS_THRESHOLDS.AT_RISK)
+        return 'at_risk';
+    return 'off_track';
+}
+/**
+ * Compute an equal-weight rolled-up progress for a cascade node.
+ *
+ * v1 weighting is intentionally equal-weight: the node's own progress counts
+ * the same as each approved child's rolled-up progress. Future ownership /
+ * complexity weighting is a documented hook (spec §4.2) — pass per-input
+ * weights here when that lands; do NOT implement weighting now.
+ *
+ * @param ownProgress - This mission's own `overallProgress` (0-100)
+ * @param childProgresses - Each approved child's `rolledUpProgress` (0-100)
+ * @returns Equal-weight average rounded to an integer 0-100; for a leaf
+ *   (no children) this equals `ownProgress` (rounded)
+ *
+ * @example
+ * ```ts
+ * computeRolledUpProgress(40, [80, 60]); // round((40 + 80 + 60) / 3) = 60
+ * computeRolledUpProgress(40, []);       // 40 (leaf)
+ * ```
+ */
+export function computeRolledUpProgress(ownProgress, childProgresses) {
+    const values = [ownProgress, ...childProgresses];
+    const total = values.reduce((sum, v) => sum + v, 0);
+    return Math.round(total / values.length);
+}
+/**
+ * Create a new KeyResult from validated input.
+ */
+export function createKeyResult(input) {
+    const now = new Date().toISOString();
+    return {
+        id: randomUUID(),
+        missionId: input.missionId,
+        title: input.title,
+        metricType: input.metricType,
+        baseline: input.baseline,
+        target: input.target,
+        current: input.baseline,
+        unit: input.unit,
+        status: 'not_started',
+        measurementSource: input.measurementSource ?? 'manual',
+        measurementConfig: input.measurementConfig,
+        linkedWorkItemIds: [],
+        measurements: [],
+        createdAt: now,
+        updatedAt: now,
+    };
+}
+/**
+ * Derive the OKR recommendation from KR status distribution.
+ *
+ * @param statuses - Array of KR statuses for a mission
+ * @param staleCycles - Number of consecutive review cycles with no progress
+ * @returns Recommendation for next action
+ */
+export function deriveOKRRecommendation(statuses, staleCycles = 0) {
+    if (statuses.length === 0)
+        return 'continue';
+    if (staleCycles >= 2)
+        return 'escalate';
+    const counts = {
+        not_started: 0,
+        on_track: 0,
+        at_risk: 0,
+        off_track: 0,
+        achieved: 0,
+    };
+    for (const s of statuses)
+        counts[s]++;
+    const total = statuses.length;
+    const healthyRatio = (counts.on_track + counts.achieved) / total;
+    const offTrackRatio = counts.off_track / total;
+    if (healthyRatio >= 0.6)
+        return 'continue';
+    if (offTrackRatio > 0.4)
+        return 'replan';
+    return 'adjust_strategy';
+}
+//# sourceMappingURL=key-result.types.js.map

package/dist/cli/backend/src/types/v2/key-result.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-result.types.js","sourceRoot":"","sources":["../../../../../../backend/src/types/v2/key-result.types.ts"],"names":[],"mappings":"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"}