trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/custom_field_values.py

@@ -0,0 +1,266 @@
+"""Typed read/write logic for per-task custom-field values (#2143, ADR-0528).
+
+Two responsibilities, both keyed off ``ProjectCustomField.field_type``:
+
+* :func:`build_custom_fields_map` — the *read* surface. Turns a task's prefetched
+  ``TaskCustomFieldValue`` rows into the flat ``{"<field_id>": <json value>}`` map
+  the Task payload (and the sync delta) carries. Unset values are omitted entirely
+  — no ``null``, no placeholder — so the board card renders nothing for them
+  (docs/design/board-card-custom-fields.md §5).
+* :func:`validate_custom_field_write` — the *write* surface. Validates a raw
+  ``{"value": …}`` payload against the field's type and returns the model-column
+  kwargs to persist, raising DRF ``ValidationError`` with the documented 400 shapes
+  (enum membership for selects, live-user FK for person, number/date parsing).
+
+Kept out of the (very large) ``serializers.py`` so the typed dispatch is unit-testable
+in isolation and shared verbatim by ``TaskSerializer``, ``SyncTaskSerializer``, and
+``TaskCustomFieldValueView`` without a circular import.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import date
+from decimal import Decimal, InvalidOperation
+from typing import TYPE_CHECKING, Any
+
+from django.contrib.auth import get_user_model
+from django.core.exceptions import ValidationError
+from rest_framework import serializers
+
+from trueppm_api.apps.projects.models import (
+    CustomFieldType,
+    ProjectCustomField,
+    TaskCustomFieldValue,
+)
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.projects.models import Task
+
+User = get_user_model()
+
+_MULTI_SELECT_MAX = 50  # mirrors the option-list cap on the field definition.
+# NUMBER values persist to a numeric(20,6) column: at most 14 integer digits and 6
+# decimal places. Bound the magnitude and quantize so a crafted value cannot overflow
+# the column (Postgres DataError → HTTP 500) or store excess precision.
+_NUMBER_MAX = Decimal(10) ** 14
+_NUMBER_QUANTUM = Decimal("0.000001")
+
+
+def _person_repr(user: Any) -> dict[str, str]:
+    """Serialize a person value the way the board already renders assignees.
+
+    ``{id, name, initials}`` so the card can draw the avatar + name with no second
+    fetch; initials fall back to the username when the name is unset, matching
+    ``RiskSerializer.get_owner_initials``.
+    """
+    name = user.get_full_name() or user.get_username()
+    parts: list[str] = []
+    if user.first_name:
+        parts.append(user.first_name[0].upper())
+    if user.last_name:
+        parts.append(user.last_name[0].upper())
+    initials = "".join(parts[:2]) if parts else user.get_username()[:2].upper()
+    return {"id": str(user.pk), "name": name, "initials": initials}
+
+
+def resolve_custom_field_value(value: TaskCustomFieldValue, field: ProjectCustomField) -> Any:
+    """Resolve one value row to its flat-dict JSON form, or ``None`` when unset.
+
+    ``None`` means "omit from the map" — the caller drops the key so an unset field
+    consumes zero card real estate. Note ``BOOLEAN`` returns ``False`` (a real value)
+    only when it was explicitly set; a never-set checkbox resolves to ``None``.
+    """
+    resolver = _VALUE_RESOLVERS.get(field.field_type)
+    return resolver(value) if resolver is not None else None
+
+
+# Per-type resolvers keyed by ``field_type`` — a flat dispatch table replacing an
+# if-ladder so each type's read shape is one entry and a new type is a one-line add.
+_VALUE_RESOLVERS: dict[str, Callable[[TaskCustomFieldValue], Any]] = {
+    CustomFieldType.TEXT: lambda v: v.value_text or None,
+    # Decimal → float for clean JSON; the web layer formats (thousands, units).
+    CustomFieldType.NUMBER: (
+        lambda v: float(v.value_number) if v.value_number is not None else None
+    ),
+    CustomFieldType.DATE: lambda v: v.value_date.isoformat() if v.value_date else None,
+    CustomFieldType.SINGLE_SELECT: lambda v: v.value_option or None,
+    CustomFieldType.MULTI_SELECT: lambda v: list(v.value_multi) if v.value_multi else None,
+    CustomFieldType.BOOLEAN: lambda v: v.value_bool,  # True / False / None
+    CustomFieldType.USER: lambda v: _person_repr(v.value_user) if v.value_user_id else None,
+}
+
+
+def build_custom_fields_map(task: Task) -> dict[str, Any]:
+    """Flat ``{"<field_id>": <value>}`` map for a task's populated custom fields.
+
+    Iterates the ``custom_field_values`` prefetch cache (never a fresh query — the
+    read paths prefetch it with ``field`` select-related). Values that resolve to
+    ``None`` (unset) are omitted, so the map only ever carries set values and an
+    unset field consumes zero card real estate.
+    """
+    out: dict[str, Any] = {}
+    for value in task.custom_field_values.all():
+        resolved = resolve_custom_field_value(value, value.field)
+        if resolved is not None:
+            out[str(value.field_id)] = resolved
+    return out
+
+
+def _clear_kwargs() -> dict[str, Any]:
+    """Column kwargs that null out every typed column (defaults for text/multi)."""
+    return {
+        "value_text": "",
+        "value_number": None,
+        "value_date": None,
+        "value_option": "",
+        "value_multi": [],
+        "value_user": None,
+        "value_bool": None,
+    }
+
+
+def _write_text(field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(raw, str):
+        raise serializers.ValidationError({"value": "value must be a string."})
+    if len(raw) > 2000:
+        raise serializers.ValidationError({"value": "value must be ≤ 2000 characters."})
+    kwargs["value_text"] = raw
+    return kwargs
+
+
+def _write_number(field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    # Reject bools (they are ``int`` subclasses) and un-parseable strings.
+    if isinstance(raw, bool) or not isinstance(raw, (int, float, str)):
+        raise serializers.ValidationError({"value": "value must be a number."})
+    try:
+        num = Decimal(str(raw))
+    except (InvalidOperation, ValueError):
+        raise serializers.ValidationError({"value": "value must be a number."}) from None
+    # This is a raw APIView, not a DRF DecimalField — validate the magnitude and
+    # finiteness here, or a crafted NaN/Infinity/over-precision value reaches the
+    # numeric(20,6) column and raises a Postgres DataError (HTTP 500) or round-trips
+    # as spec-invalid JSON ``NaN`` on every subsequent read (the #2123-2127 fuzz-500
+    # class; the nightly Schemathesis job is schedule-only and won't catch it).
+    if not num.is_finite():
+        raise serializers.ValidationError({"value": "value must be a finite number."})
+    if abs(num) >= _NUMBER_MAX:
+        raise serializers.ValidationError(
+            {"value": "value is out of range (at most 14 integer digits)."}
+        )
+    kwargs["value_number"] = num.quantize(_NUMBER_QUANTUM)  # clamp to 6 dp
+    return kwargs
+
+
+def _write_date(field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(raw, str):
+        raise serializers.ValidationError({"value": "value must be an ISO-8601 date string."})
+    try:
+        kwargs["value_date"] = date.fromisoformat(raw)
+    except ValueError:
+        raise serializers.ValidationError(
+            {"value": "value must be an ISO-8601 date (YYYY-MM-DD)."}
+        ) from None
+    return kwargs
+
+
+def _write_boolean(field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(raw, bool):
+        raise serializers.ValidationError({"value": "value must be a boolean."})
+    kwargs["value_bool"] = raw
+    return kwargs
+
+
+def _write_single_select(
+    field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]
+) -> dict[str, Any]:
+    if not isinstance(raw, str):
+        raise serializers.ValidationError({"value": "value must be an option value string."})
+    allowed = {opt.get("value") for opt in field.options}
+    if raw not in allowed:
+        raise serializers.ValidationError(
+            {"value": f"{raw!r} is not a valid option for field {field.name!r}."}
+        )
+    kwargs["value_option"] = raw
+    return kwargs
+
+
+def _write_multi_select(
+    field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]
+) -> dict[str, Any]:
+    if not isinstance(raw, list) or not all(isinstance(v, str) for v in raw):
+        raise serializers.ValidationError({"value": "value must be a list of option values."})
+    if len(raw) > _MULTI_SELECT_MAX:
+        raise serializers.ValidationError(
+            {"value": f"value must contain at most {_MULTI_SELECT_MAX} options."}
+        )
+    allowed = {opt.get("value") for opt in field.options}
+    for v in raw:
+        if v not in allowed:
+            raise serializers.ValidationError(
+                {"value": f"{v!r} is not a valid option for field {field.name!r}."}
+            )
+    # De-duplicate while preserving author order — an idempotent, forgiving write.
+    kwargs["value_multi"] = list(dict.fromkeys(raw))
+    return kwargs
+
+
+def _write_user(field: ProjectCustomField, raw: Any, kwargs: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(raw, str):
+        raise serializers.ValidationError({"value": "value must be a user id string."})
+    # The person must be a live member of the field's project — mirrors the
+    # assignee membership guard (#684) so a person field cannot smuggle a
+    # non-member (or a user from another project) onto the task.
+    from trueppm_api.apps.access.models import ProjectMembership
+
+    # One generic message for both "no such user" and "exists but not a member" so
+    # the endpoint is not an existence oracle for arbitrary user ids.
+    not_member = serializers.ValidationError(
+        {"value": f"user {raw!r} is not a valid member of this project."}
+    )
+    try:
+        user = User.objects.get(pk=raw)
+    except (User.DoesNotExist, ValueError, ValidationError):
+        raise not_member from None
+    # ``live()``, not ``objects`` (#3411): revoking access soft-deletes the membership
+    # row against an unconditional (project, user) constraint, so an unfloored ``exists``
+    # accepts someone who has already left the project as a valid value for the field.
+    is_member = (
+        ProjectMembership.live().filter(project_id=field.project_id, user_id=user.pk).exists()
+    )
+    if not is_member:
+        raise not_member
+    kwargs["value_user"] = user
+    return kwargs
+
+
+# Per-type write validators keyed by ``field_type``. Each takes the field, the raw
+# JSON value and the pre-cleared kwargs, validates and sets exactly one typed column,
+# and returns the kwargs (or raises DRF ``ValidationError`` → HTTP 400). Splitting the
+# old single if-ladder into one function per type keeps each — and the dispatcher —
+# well under the cognitive-complexity budget.
+_VALUE_WRITERS: dict[str, Callable[[ProjectCustomField, Any, dict[str, Any]], dict[str, Any]]] = {
+    CustomFieldType.TEXT: _write_text,
+    CustomFieldType.NUMBER: _write_number,
+    CustomFieldType.DATE: _write_date,
+    CustomFieldType.BOOLEAN: _write_boolean,
+    CustomFieldType.SINGLE_SELECT: _write_single_select,
+    CustomFieldType.MULTI_SELECT: _write_multi_select,
+    CustomFieldType.USER: _write_user,
+}
+
+
+def validate_custom_field_write(field: ProjectCustomField, raw: Any) -> dict[str, Any]:
+    """Validate a raw value against ``field``'s type → model-column kwargs.
+
+    Raises DRF ``ValidationError`` (HTTP 400) with a ``{"value": …}`` shape on any
+    type mismatch. The returned dict always sets exactly one typed column and leaves
+    the rest at their empty defaults, so applying it over an existing row cleanly
+    overwrites a prior value (the write path is a full upsert, not a partial merge).
+    """
+    writer = _VALUE_WRITERS.get(field.field_type)
+    if writer is None:
+        raise serializers.ValidationError(
+            {"value": f"unsupported field type {field.field_type!r}."}
+        )
+    return writer(field, raw, _clear_kwargs())

trueppm_api/apps/projects/decisions_services.py

@@ -0,0 +1,132 @@
+"""Decisions-view visibility gate + queryset helpers (ADR-0167, #748).
+
+The Decisions view surfaces every task note flagged ``decision=True`` for a project,
+optionally scoped to one sprint. Visibility is team-owned: by default the list is
+readable by the team and the PM only; an *oversight reader* (a project member who is
+not on the default team and is below Admin) sees it only once a project Admin opts in
+via :class:`~trueppm_api.apps.projects.models.ProjectDecisionsPolicy`.
+
+These helpers are pure (no view imports) so both the ``ProjectViewSet.decisions``
+list action and the consent ``ProjectDecisionsPolicyView`` can share the gate without
+an import cycle.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db import transaction
+from django.db.models import F, QuerySet
+
+from trueppm_api.apps.access.models import Role
+from trueppm_api.apps.access.permissions import _membership_role
+from trueppm_api.apps.projects.models import Project, ProjectDecisionsPolicy, TaskNote
+
+
+def get_or_create_decisions_policy(project: Project) -> ProjectDecisionsPolicy:
+    """Lazily materialize the project's decisions-visibility policy.
+
+    Mirrors ``signal_privacy_services.get_or_create_policy`` — the row is created on
+    first access so existing projects need no data migration. A fresh row carries the
+    default-closed posture (``oversight_visible=False``).
+    """
+    policy, _ = ProjectDecisionsPolicy.objects.get_or_create(project=project)
+    return policy
+
+
+def set_oversight_visible(
+    policy: ProjectDecisionsPolicy, oversight_visible: bool
+) -> ProjectDecisionsPolicy:
+    """Flip the team's oversight-visibility switch and notify live clients (#4283).
+
+    Mirrors ``signal_privacy_services.set_signal_audience``'s layering: the write and
+    its live-client broadcast live in the one chokepoint every writer of this field
+    passes through, so a future caller can never persist the switch without
+    broadcasting it — the defect this closes (``ProjectDecisionsPolicyView.patch``
+    saved the policy with no broadcast anywhere in the write path). Plain ``save()``
+    (not ``update_fields``) so ``VersionedModel`` bumps ``server_version`` and
+    ``HistoricalRecords`` captures who flipped the switch.
+    """
+    policy.oversight_visible = oversight_visible
+    policy.save()
+    _emit_oversight_visible_changed(policy.project_id, oversight_visible)
+    return policy
+
+
+def _emit_oversight_visible_changed(project_id: Any, oversight_visible: bool) -> None:
+    """Broadcast the oversight-visibility change on commit (#4283).
+
+    Mirrors ``signal_privacy_services._emit_consent_changed``'s deferral: the write
+    must commit before a peer's refetch could observe the new value, so the
+    broadcast is deferred with ``transaction.on_commit()`` per project convention.
+    """
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+
+    project_id_str = str(project_id)
+    transaction.on_commit(
+        lambda: broadcast_board_event(
+            project_id_str,
+            "decisions_policy_changed",
+            {"id": project_id_str, "oversight_visible": oversight_visible},
+        )
+    )
+
+
+def can_read_decisions(
+    request: Any,
+    project_id: Any,
+    *,
+    policy: ProjectDecisionsPolicy | None = None,
+) -> bool:
+    """Whether the requester may read the project's Decisions view (ADR-0167 §3).
+
+    "Team + PM" = ``Role.MEMBER`` (Team Member) and above — the project's contributors and
+    managers, who see the log by default. A requester below the Member band — a Viewer, or
+    an Enterprise read-augmented/auditor role in the reserved 1–99 ordinal band (ADR-0072) —
+    is the single-project stand-in for a PMO/oversight reader and is suppressed until the
+    team opts in (``oversight_visible``).
+
+    Role, not team membership, is the discriminator: every ``ProjectMembership`` mirrors
+    onto the default team (teams/signals.py), so ``is_team_member`` cannot tell a
+    read-only observer apart from a contributor — the Role ladder can. ``policy`` may be
+    passed to avoid a second lookup; it is fetched lazily otherwise (read path, no row
+    creation).
+    """
+    role = _membership_role(request, project_id)
+    if role is None:
+        return False
+    if role >= Role.MEMBER:
+        return True
+    if policy is None:
+        # Read path: do not create the row on a denied/allowed check. Absent row ⇒
+        # default-closed, so a missing policy resolves to "not oversight-visible".
+        oversight_visible = (
+            ProjectDecisionsPolicy.objects.filter(project_id=project_id)
+            .values_list("oversight_visible", flat=True)
+            .first()
+            or False
+        )
+    else:
+        oversight_visible = policy.oversight_visible
+    return bool(oversight_visible)
+
+
+def decision_notes_queryset(project_id: Any, sprint_id: str | None = None) -> QuerySet[TaskNote]:
+    """Decision-flagged, non-deleted notes for a project, optionally one sprint.
+
+    Ordered newest-sprint-first then newest-decision-first so the web client can group
+    by sprint with the most recent sprint (and the backlog group, sprint null) leading.
+    ``select_related`` pulls the task + sprint + author so the serializer renders the
+    task/sprint context and the author mini without an N+1.
+    """
+    qs = TaskNote.objects.filter(
+        task__project_id=project_id,
+        is_deleted=False,
+        decision=True,
+    ).select_related("author", "task", "task__sprint")
+    if sprint_id is not None:
+        qs = qs.filter(task__sprint_id=sprint_id)
+    # NULLS LAST on sprint start so the backlog (sprint-less) group trails the dated
+    # sprints — Postgres sorts NULLs first under a bare DESC, so make it explicit;
+    # -created_at orders decisions newest-first within each sprint.
+    return qs.order_by(F("task__sprint__start_date").desc(nulls_last=True), "-created_at")

trueppm_api/apps/projects/decisions_views.py

@@ -0,0 +1,97 @@
+"""Decisions-view visibility consent endpoint (ADR-0167 §3, #748).
+
+Surface:
+  GET   /api/v1/projects/<project_pk>/decisions-policy/   — read posture (+ can_edit)
+  PATCH /api/v1/projects/<project_pk>/decisions-policy/   — set oversight_visible (Admin+)
+
+The single ``oversight_visible`` switch is the team's upward-exposure control for the
+project Decisions view. Default-closed; widening to oversight readers is a project-Admin
+act (the team-admin authority in the OSS single-project model). The matching read gate is
+``decisions_services.can_read_decisions``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from drf_spectacular.utils import extend_schema
+from rest_framework import serializers
+from rest_framework.exceptions import PermissionDenied
+from rest_framework.generics import get_object_or_404
+from rest_framework.permissions import IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from trueppm_api.apps.access.models import Role
+from trueppm_api.apps.access.permissions import (
+    IsProjectMember,
+    IsProjectNotArchived,
+    _membership_role,
+)
+from trueppm_api.apps.projects.decisions_services import (
+    get_or_create_decisions_policy,
+    set_oversight_visible,
+)
+from trueppm_api.apps.projects.models import Project
+
+
+class DecisionsPolicyReadSerializer(serializers.Serializer[Any]):
+    """Read shape: the current posture plus whether the requester may change it."""
+
+    oversight_visible = serializers.BooleanField()
+    can_edit = serializers.BooleanField()
+
+
+class DecisionsPolicyWriteSerializer(serializers.Serializer[Any]):
+    """PATCH body — flip the team's single oversight-visibility switch."""
+
+    oversight_visible = serializers.BooleanField()
+
+
+class ProjectDecisionsPolicyView(APIView):
+    """GET the decisions-visibility posture; PATCH ``oversight_visible`` (Admin+)."""
+
+    permission_classes = [IsAuthenticated, IsProjectMember, IsProjectNotArchived]  # noqa: RUF012
+
+    def _project(self, project_pk: str) -> Project:
+        project = get_object_or_404(Project, pk=project_pk, is_deleted=False)
+        self.check_object_permissions(self.request, project)
+        return project
+
+    def _payload(
+        self, request: Request, project_id: Any, oversight_visible: bool
+    ) -> dict[str, Any]:
+        role = _membership_role(request, project_id)
+        can_edit = role is not None and role >= Role.ADMIN
+        return {"oversight_visible": oversight_visible, "can_edit": can_edit}
+
+    @extend_schema(
+        summary="Read the Decisions-view visibility posture",
+        responses=DecisionsPolicyReadSerializer,
+    )
+    def get(self, request: Request, project_pk: str) -> Response:
+        project = self._project(project_pk)
+        policy = get_or_create_decisions_policy(project)
+        return Response(self._payload(request, project.pk, policy.oversight_visible))
+
+    @extend_schema(
+        summary="Set whether oversight readers may see the Decisions view (Admin+)",
+        request=DecisionsPolicyWriteSerializer,
+        responses=DecisionsPolicyReadSerializer,
+    )
+    def patch(self, request: Request, project_pk: str) -> Response:
+        project = self._project(project_pk)
+        role = _membership_role(request, project.pk)
+        # Team-admin consent (ADR-0167 §3): only a project Admin+ may widen or narrow the
+        # team's upward exposure. Read stays any-member; the write is the consent act.
+        if role is None or role < Role.ADMIN:
+            raise PermissionDenied("Only a project admin can change who sees the Decisions view.")
+        body = DecisionsPolicyWriteSerializer(data=request.data)
+        body.is_valid(raise_exception=True)
+        policy = get_or_create_decisions_policy(project)
+        # set_oversight_visible is the one chokepoint that both saves (bumping
+        # server_version / HistoricalRecords) and broadcasts decisions_policy_changed
+        # on commit (#4283) — mirrors signal_privacy_services' write+broadcast layering.
+        policy = set_oversight_visible(policy, body.validated_data["oversight_visible"])
+        return Response(self._payload(request, project.pk, policy.oversight_visible))

trueppm_api/apps/projects/estimation_scale.py

@@ -0,0 +1,126 @@
+"""Workspace → Program → Project resolution for the estimation scale (ADR-0510, #2027).
+
+Story-point estimates are stored as a single integer (``Task.story_points`` /
+``BacklogItem.story_points``). The ``estimation_scale`` enum decides only which
+input widget and display label the client renders for that integer — Fibonacci,
+Linear, or T-shirt — never the stored value or any velocity/rollup math. The scale
+is set at the workspace by default and may be overridden per program or project.
+The *effective* scale is resolved here, computed-on-read (ADR-0108) — there is no
+stored/denormalized effective column to keep in sync. Clients (web, mobile, MCP)
+read the serializer's ``effective_estimation_scale``; they never re-implement this
+precedence.
+
+Precedence: project override → program override → workspace value.
+
+Unlike the calendar (ADR-0441) and duration policy (ADR-0151), the estimation scale
+has **no enforcement seam** — it is a plain PO/team preference, freely overridable
+at every scope, and OSS by construction (ADR-0510, enterprise-check). Adding a lock
+flag, override-suppression, or an inheritance-change audit would import the
+Enterprise "policy-enforced inheritance" surface and belongs in trueppm-enterprise.
+The Workspace root is non-null (default Fibonacci), so the chain always resolves to
+a real value; there is no ``system_default`` terminal (contrast the calendar's
+Mon-Fri/8h/UTC backstop).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.projects.models import Program, Project
+    from trueppm_api.apps.workspace.models import Workspace
+
+#: The inheritable field, identically named on Workspace (non-null root), Program,
+#: and Project (nullable override).
+ESTIMATION_SCALE_FIELD = "estimation_scale"
+
+#: Which scope supplied the effective scale. No ``system_default`` — the Workspace
+#: root is non-null, so resolution always terminates in a real scope.
+EstimationScaleSource = Literal["project", "program", "workspace"]
+
+
+def _program_of(obj: Program | Project) -> Program | None:
+    """The owning program of a project, or None for a program/standalone project."""
+    from trueppm_api.apps.projects.models import Program
+
+    if isinstance(obj, Program):
+        return None
+    return obj.program if obj.program_id else None
+
+
+def _parent_value(obj: Program | Project, *, workspace: Workspace) -> str:
+    """Resolve the scale from ``obj``'s parent scope up to the workspace.
+
+    A Program's parent is the workspace. A Project's parent is its program (whose
+    own override resolves up to the workspace) or, if standalone, the workspace.
+    """
+    program = _program_of(obj)
+    if program is not None:
+        program_override = getattr(program, ESTIMATION_SCALE_FIELD)
+        if program_override:
+            return str(program_override)
+    return str(getattr(workspace, ESTIMATION_SCALE_FIELD))
+
+
+def resolve_effective_estimation_scale(
+    obj: Program | Project,
+    *,
+    workspace: Workspace | None = None,
+) -> str:
+    """Resolve the effective estimation scale for a program or project.
+
+    ``workspace`` may be passed to avoid re-loading the singleton per object when
+    resolving a list (the serializer caches it once); otherwise it is loaded here.
+    Returns an :class:`~trueppm_api.apps.projects.models.EstimationScale` value
+    (``fibonacci`` | ``linear`` | ``tshirt``).
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+
+    own = getattr(obj, ESTIMATION_SCALE_FIELD)  # nullable override on Program/Project
+    if own:
+        return str(own)
+    return _parent_value(obj, workspace=workspace)
+
+
+def resolve_inherited_estimation_scale(
+    obj: Program | Project,
+    *,
+    workspace: Workspace | None = None,
+) -> str:
+    """Scale ``obj`` would inherit if its own override were cleared.
+
+    Drives a settings "Inherit (<value>)" affordance — it deliberately skips
+    ``obj``'s own override and resolves from the parent scope up.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+    return _parent_value(obj, workspace=workspace)
+
+
+def resolve_estimation_scale_source(
+    obj: Program | Project,
+    *,
+    workspace: Workspace | None = None,
+) -> EstimationScaleSource:
+    """Which scope supplied :func:`resolve_effective_estimation_scale` for ``obj``.
+
+    The breadcrumb the settings UI reads to explain which scope set the scale,
+    without re-deriving the precedence. ``workspace`` is accepted for signature
+    symmetry with the other resolvers (it is never needed — the terminal scope is
+    "workspace" by elimination).
+    """
+    from trueppm_api.apps.projects.models import Program
+
+    if not isinstance(obj, Program) and getattr(obj, ESTIMATION_SCALE_FIELD):
+        return "project"
+    if isinstance(obj, Program) and getattr(obj, ESTIMATION_SCALE_FIELD):
+        return "program"
+    program = _program_of(obj)
+    if program is not None and getattr(program, ESTIMATION_SCALE_FIELD):
+        return "program"
+    return "workspace"