orchestrata_ultimate.core.domain.goal

Reference › orchestrata_ultimate › core › domain › goal

The portfolio-goal domain models of SPEC-012, shared by the session layer and the agents layer. They live in core so that the session persistence layer (ContextFileManager, ProjectState.portfolio_goals) and the product-manager volk's GoalRegistry can both use them without an upward import; session.models re-exports them for backward compatibility, and agents.volks.pm.goal_registry imports them.

PortfolioGoalStatus is a string enum with the states active, running, completed, blocked, deferred and cancelled; it is distinct from the plain-string status of the single SPEC-023 session goal. PortfolioGoalPriority holds the priority levels (the default is P1). PortfolioSuccessCriteria is a Pydantic model whose defaults require passing tests, 90 percent coverage, no spec-coverage minimum and at most 20 iterations, with a custom dictionary for extras. PortfolioGoal records the goal id (a UUID prefix by default), description, criteria, status, priority, progress percentage, iterations spent, gap analysis, assigned volks, creation and completion times, last result and notes. Each class is annotated with @traces for SPEC-012.

At a glance

Class diagram

Dependency diagram

API

Classes

PortfolioGoalStatus (enum)

Bases: StrEnum · Decorators: traces(spec='012', story='US-012-Goals', reqs=['REQ-012-036']) · Line 24

Portfolio goal lifecycle states.

PortfolioGoalPriority (enum)

Bases: StrEnum · Decorators: traces(spec='012', story='US-012-Goals', reqs=['REQ-012-037']) · Line 41

Portfolio goal priority levels.

PortfolioSuccessCriteria (pydantic)

Bases: BaseModel · Decorators: traces(spec='012', story='US-012-Goals', reqs=['REQ-012-038']) · Line 51

Completion criteria for a portfolio goal.

PortfolioGoal (pydantic)

Bases: BaseModel · Decorators: traces(spec='012', story='US-012-Goals', reqs=['REQ-012-039']) · Line 70

A tracked portfolio goal with PM-managed lifecycle (SPEC-012).

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/domain/goal.py

"""Portfolio goal domain models (SPEC-012).

Shared layer-1 domain types for PM-managed portfolio goals: lifecycle status,
priority, success criteria, and the goal record itself. These live in ``core``
(not ``session``) so BOTH the session persistence layer (SPEC-023
``ContextFileManager`` / ``ProjectState.portfolio_goals``) and the agents layer
(``U:PM``'s ``GoalRegistry``) can depend on them WITHOUT an upward cross-layer
import — the portfolio-goal domain model is a shared kernel concern, not a
session-only one. ``session.models`` re-exports these for backward compatibility
(``from orchestrata_ultimate.session.models import PortfolioGoal`` still works).
"""

import uuid
from datetime import UTC, datetime
from enum import StrEnum
from typing import Any

from pydantic import BaseModel, Field

from orchestrata_ultimate.core.base.traces import traces


@traces(spec="012", story="US-012-Goals", reqs=["REQ-012-036"])
class PortfolioGoalStatus(StrEnum):
    """Portfolio goal lifecycle states.

    Distinct from the singular SPEC-023 session ``Goal.status`` (a plain
    ``str``): portfolio goals are PM-managed, multiple-at-once, and carry
    their own richer lifecycle.
    """

    ACTIVE = "active"
    RUNNING = "running"
    COMPLETED = "completed"
    BLOCKED = "blocked"
    DEFERRED = "deferred"
    CANCELLED = "cancelled"


@traces(spec="012", story="US-012-Goals", reqs=["REQ-012-037"])
class PortfolioGoalPriority(StrEnum):
    """Portfolio goal priority levels."""

    P0 = "P0"
    P1 = "P1"
    P2 = "P2"
    P3 = "P3"


@traces(spec="012", story="US-012-Goals", reqs=["REQ-012-038"])
class PortfolioSuccessCriteria(BaseModel):
    """Completion criteria for a portfolio goal.

    Attributes:
        tests_pass: Whether all tests must pass.
        min_coverage_pct: Minimum code coverage percentage.
        min_spec_coverage_pct: Minimum spec coverage percentage.
        max_iterations: Maximum iterations before marking blocked.
        custom: Additional custom criteria as key-value pairs.
    """

    tests_pass: bool = True
    min_coverage_pct: float = 90.0
    min_spec_coverage_pct: float = 0.0
    max_iterations: int = 20
    custom: dict[str, Any] = Field(default_factory=dict)


@traces(spec="012", story="US-012-Goals", reqs=["REQ-012-039"])
class PortfolioGoal(BaseModel):
    """A tracked portfolio goal with PM-managed lifecycle (SPEC-012).

    Persists in context.json under ``state.portfolio_goals`` — a LIST,
    distinct from the singular SPEC-023 session goal at ``state.goal``.
    ``U:PM`` tracks multiple portfolio goals concurrently (priority, success
    criteria, iteration count, gap analysis, assigned volks), independent of
    whichever single goal the current session has committed to.
    """

    goal_id: str = Field(default_factory=lambda: str(uuid.uuid4())[:8])
    description: str = ""
    success_criteria: PortfolioSuccessCriteria = Field(
        default_factory=PortfolioSuccessCriteria
    )
    status: PortfolioGoalStatus = PortfolioGoalStatus.ACTIVE
    priority: PortfolioGoalPriority = PortfolioGoalPriority.P1
    progress_pct: float = 0.0
    iterations_spent: int = 0
    gap_analysis: list[str] = Field(default_factory=list)
    assigned_volks: list[str] = Field(default_factory=list)
    created_at: str = Field(default_factory=lambda: datetime.now(UTC).isoformat())
    completed_at: str | None = None
    last_result: dict[str, Any] = Field(default_factory=dict)
    notes: str = ""