trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/backlog_services.py

@@ -0,0 +1,324 @@
+"""Service layer for the program backlog pull-down (ADR-0069 Erratum, #737).
+
+The pull action is the one place where a program-level ``BacklogItem`` crosses
+into a project: it converts a PROPOSED item into a project-backlog ``Task``
+(``status=BACKLOG``, ``sprint=NULL``) and records the conversion on the item.
+Sprint sovereignty is preserved by design — pull never assigns a sprint
+(Morgan's VoC blocker, resolved in ADR-0069).
+
+Kept as a service (not inline in the view) so the atomic transition is testable
+in isolation and reusable by a future batch-pull from Sprint Planning.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from django.db import IntegrityError, transaction
+from django.db.models import Max
+from django.utils import timezone
+
+from trueppm_api.apps.projects.models import (
+    BacklogItem,
+    BacklogItemStatus,
+    BacklogItemType,
+    Label,
+    LabelColor,
+    Project,
+    Task,
+    TaskLabel,
+    TaskStatus,
+    TaskType,
+)
+
+# Map the program intake taxonomy (ADR-0069) onto the project work-item taxonomy
+# (ADR-0105). The two enums are reconciled (#1995): every intake type maps to a
+# distinct Task type so a pulled bug/spike/chore keeps its kind instead of
+# silently collapsing to a plain task. ``chore`` is the intake name for
+# ``TaskType.TECH_DEBT``; ``feature`` has no Task analogue and maps to ``TASK``.
+_ITEM_TYPE_TO_TASK_TYPE: dict[str, TaskType] = {
+    BacklogItemType.EPIC: TaskType.EPIC,
+    BacklogItemType.STORY: TaskType.STORY,
+    BacklogItemType.TASK: TaskType.TASK,
+    BacklogItemType.BUG: TaskType.BUG,
+    BacklogItemType.SPIKE: TaskType.SPIKE,
+    BacklogItemType.CHORE: TaskType.TECH_DEBT,
+    BacklogItemType.FEATURE: TaskType.TASK,
+}
+
+
+class BacklogItemNotPullable(Exception):
+    """Raised when a pull is attempted on an item that is not PROPOSED.
+
+    The view maps this to ``409 Conflict`` — the item was already pulled or
+    archived (or a concurrent pull won the row lock first).
+    """
+
+
+class CrossProgramPullError(Exception):
+    """Raised when the pull target project does not belong to the item's program.
+
+    The view maps this to ``400 Bad Request``. Single-program scoping is the OSS
+    boundary (ADR-0069): a program backlog item can only be pulled into one of
+    its own program's projects, never into another program's project.
+    """
+
+
+def pull_to_project_backlog(
+    item_id: str,
+    project: Project,
+    actor: Any,
+) -> Task:
+    """Atomically convert a PROPOSED ``BacklogItem`` into a project-backlog Task.
+
+    Locks the item ``FOR UPDATE`` and asserts it is still PROPOSED before doing
+    any work, so two concurrent pulls cannot both succeed — the loser raises
+    :class:`BacklogItemNotPullable` (→ 409). The new Task lands in the project
+    backlog (``status=BACKLOG``, ``sprint=None``); the item is flipped to PULLED
+    with ``pulled_task``/``pulled_at``/``pulled_by`` recorded. Both rows bump
+    ``server_version`` via their ``save()``.
+
+    On commit it enqueues a CPM recalculation (existing scheduling outbox — no
+    new outbox category), broadcasts a ``task_created`` board event, and fires the
+    ``task.created`` outbound webhook (#752) — matching every other Task-create
+    path so external subscribers see backlog pulls like any other create. All
+    three are deferred with ``transaction.on_commit`` so a rolled-back pull never
+    leaks a recalc request, a phantom WS event, or a webhook delivery.
+
+    Args:
+        item_id: PK of the ``BacklogItem`` to pull.
+        project: The resolved target ``Project`` (must belong to the item's program).
+        actor: The user performing the pull (recorded as ``pulled_by``).
+
+    Returns:
+        The created project-backlog ``Task``.
+
+    Raises:
+        BacklogItem.DoesNotExist: if no such item exists.
+        CrossProgramPullError: if ``project`` is not in the item's program.
+        BacklogItemNotPullable: if the item is not in PROPOSED status.
+    """
+    # Call-time import (not module-level) to avoid a views→services→views cycle.
+    # By the time this service runs, the app is fully loaded, so reusing the
+    # canonical task payload builder keeps the pull's task.created shape identical
+    # to the REST create path with zero drift risk.
+    from trueppm_api.apps.access.permissions import assert_project_not_archived
+    from trueppm_api.apps.projects.views import _task_webhook_payload
+    from trueppm_api.apps.scheduling.services import enqueue_recalculate
+    from trueppm_api.apps.sync.broadcast import broadcast_board_event
+    from trueppm_api.apps.webhooks.dispatch import dispatch_webhooks
+
+    # A pull creates a Task, and archived plans take no writes (#3354). The view
+    # checks this too, but archived is lifecycle state — a property of the target
+    # plan, not of the caller — so it holds for every caller rather than only for
+    # one that arrives through DRF. Every caller is a view today; the point is that
+    # nothing makes that stay true. Placed before the transaction so nothing is
+    # opened on a write that must not happen.
+    assert_project_not_archived(project.pk)
+
+    new_label_ids: list[str] = []
+    with transaction.atomic():
+        item = BacklogItem.objects.select_for_update().get(pk=item_id, is_deleted=False)
+
+        if project.program_id != item.program_id:
+            raise CrossProgramPullError("The target project is not part of this program.")
+
+        if item.status != BacklogItemStatus.PROPOSED:
+            raise BacklogItemNotPullable(
+                f"This item is '{item.status}' and can no longer be pulled."
+            )
+
+        task = Task.objects.create(
+            project=project,
+            name=item.title,
+            # BacklogItem.description maps to Task.notes — Task has no separate
+            # description field; the Board/drawer render notes as the body.
+            notes=item.description,
+            story_points=item.story_points,
+            # The PO's intake ordering is the whole point of ranking a program
+            # backlog, and it is not reconstructable after the crossing — there is
+            # no un-pull endpoint, so a lost rank cannot be recovered by undoing.
+            # Both fields are nullable PositiveIntegerFields meaning "lower = higher
+            # priority", so the raw value carries: it preserves relative order among
+            # items pulled from the same pool. Ranks are not unique and ties already
+            # break on a secondary sort, so colliding with an existing project task's
+            # rank is harmless — whereas leaving it null sorts the pulled item last
+            # (the 9999 client sentinel), which is the defect (#2906).
+            priority_rank=item.priority_rank,
+            status=TaskStatus.BACKLOG,
+            sprint=None,
+            # ADR-0105: carry the intake item's type into the project work-item
+            # taxonomy so a pulled story/bug/spike keeps its kind. The taxonomies
+            # are reconciled (#1995), so ``.get`` always hits; the TASK fallback is
+            # defensive only (an unknown value can no longer be created).
+            type=_ITEM_TYPE_TO_TASK_TYPE.get(item.item_type, TaskType.TASK),
+        )
+
+        # Carry the intake item's free-text tags onto the task as project labels
+        # (#1992) so a PO's thematic grouping survives the crossing. Runs inside
+        # the atomic block so a rolled-back pull leaves no orphan labels.
+        new_label_ids = _apply_tags_as_labels(task, project, item.tags, actor)
+
+        item.status = BacklogItemStatus.PULLED
+        item.pulled_task = task
+        item.pulled_at = timezone.now()
+        item.pulled_by = actor if getattr(actor, "is_authenticated", False) else None
+        # server_version is bumped automatically by VersionedModel.save() (it is
+        # stripped from update_fields and incremented via F()), so it is omitted here.
+        item.save(update_fields=["status", "pulled_task", "pulled_at", "pulled_by"])
+
+    project_id = str(project.pk)
+    task_id = str(task.pk)
+    # source="backlog_pull" tells external consumers which surface originated the
+    # create (ADR-0065 X-Source semantics) so a pull is distinguishable from a
+    # board/schedule/sync create on the same task.created event.
+    webhook_payload = _task_webhook_payload(task, source="backlog_pull")
+    # CPM recalc via the existing scheduling outbox (ADR-0027). A BACKLOG task is
+    # excluded from the CPM graph, so this coalesces to a no-op run today, but we
+    # keep it on the standard Task-create path for consistency and forward-safety.
+    transaction.on_commit(lambda: enqueue_recalculate(project_id))
+    transaction.on_commit(
+        lambda: broadcast_board_event(project_id, "task_created", {"id": task_id})
+    )
+
+    # Any labels coined from the item's tags are new project vocabulary — tell open
+    # boards/label managers so they can render the pulled task's pills (#1992). Bind
+    # the id through a function arg so closure late-binding can't collapse the loop's
+    # events to the last id.
+    def _broadcast_label(lid: str) -> None:
+        transaction.on_commit(
+            lambda: broadcast_board_event(project_id, "label_created", {"id": lid})
+        )
+
+    for _label_id in new_label_ids:
+        _broadcast_label(_label_id)
+
+    # Bind the payload via a default arg so closure late-binding can never swap it
+    # if this function grows more branches later (matches inbound_sync.py).
+    def _dispatch(pid: str = project_id, wp: dict[str, Any] = webhook_payload) -> None:
+        dispatch_webhooks(pid, "task.created", wp)
+
+    transaction.on_commit(_dispatch)
+    return task
+
+
+def _apply_tags_as_labels(
+    task: Task,
+    project: Project,
+    tags: list[str],
+    actor: Any,
+) -> list[str]:
+    """Carry a pulled item's free-text tags onto the task as project labels (#1992).
+
+    Each tag becomes — or, case-insensitively, reuses — a project-scoped ``Label``
+    and is attached to ``task`` via ``TaskLabel``. Reuse keeps the catalog from
+    sprouting a near-duplicate on every pull; new labels take the neutral default
+    slot (``SLATE``) appended to the end of the palette order, which a project admin
+    can recolor later. Idempotent per tag via ``TaskLabel.get_or_create``.
+
+    Must be called inside the pull's ``transaction.atomic`` block so a rolled-back
+    pull leaves no orphan labels. The label soft cap is honored: once the project is
+    at the ceiling, further *new* tags are skipped (existing matches still attach) so
+    a pull can never blow past the curation floor the ``LabelViewSet`` enforces.
+
+    Args:
+        task: The freshly created project-backlog Task to label.
+        project: The task's project (labels are project-scoped).
+        tags: The item's tags — already normalized (trimmed, de-duped) by the
+            serializer's ``validate_tags``.
+        actor: The pulling user, recorded as ``created_by`` on any new label.
+
+    Returns:
+        The ids of labels *created* here (not reused), so the caller can broadcast
+        ``label_created`` once the transaction commits.
+    """
+    if not tags:
+        return []
+    # Call-time import mirrors the pull's views import — avoids a services→views cycle.
+    from trueppm_api.apps.projects.views import _label_soft_cap
+
+    cap = _label_soft_cap()
+    live = Label.objects.filter(project=project, is_deleted=False)
+    label_count = live.count()
+    next_position = (live.aggregate(m=Max("position"))["m"] or 0) + 1
+    creator = actor if getattr(actor, "is_authenticated", False) else None
+
+    created_ids: list[str] = []
+    for tag in tags:
+        # Label.name is capped at 50 chars; BacklogItem tags are unbounded, so clamp
+        # to keep an over-long tag from raising instead of degrading gracefully.
+        name = tag[:50]
+        existing = Label.objects.filter(
+            project=project, name__iexact=name, is_deleted=False
+        ).first()
+        if existing is not None:
+            TaskLabel.objects.get_or_create(task=task, label=existing)
+            continue
+        if label_count >= cap:
+            # At the curation ceiling — skip coining a new label but keep going;
+            # a pull must not fail because the project's label catalog is full.
+            continue
+        label, created = _coin_label(project, name, next_position, creator)
+        if label is None:
+            continue
+        if created:
+            next_position += 1
+            label_count += 1
+            created_ids.append(str(label.pk))
+        TaskLabel.objects.get_or_create(task=task, label=label)
+    return created_ids
+
+
+def _coin_label(
+    project: Project,
+    name: str,
+    position: int,
+    creator: Any,
+) -> tuple[Any, bool]:
+    """Create a new project label at ``position``, or reuse the race winner.
+
+    Returns ``(label, created)`` where ``created`` is True only when this call
+    coined the label (so the caller can bump the position/count and broadcast).
+
+    Savepoint the create so a concurrent pull that coined the same tag first raises
+    only a local IntegrityError (on uniq_label_name_per_project) instead of poisoning
+    the whole pull transaction. Without the nested atomic the outer pull would roll
+    back to a transient 500. On a lost race the other transaction's label is now
+    committed and visible; reuse it (exact-name match, since the unique constraint is
+    on exact (project, name)).
+    """
+    try:
+        with transaction.atomic():
+            label = Label.objects.create(
+                project=project,
+                name=name,
+                color=LabelColor.SLATE,
+                position=position,
+                created_by=creator,
+            )
+    except IntegrityError:
+        return Label.objects.filter(project=project, name=name, is_deleted=False).first(), False
+    return label, True
+
+
+def reset_pulled_item_on_task_delete(task_id: str) -> None:
+    """Reset a BacklogItem to PROPOSED when its pulled Task is (soft-)deleted.
+
+    Rollback path (ADR-0069): if the Task created by a pull is deleted, the
+    originating item must become re-pullable. ``pulled_task`` is ``SET_NULL`` so
+    deletion never cascades to the item; this restores the lifecycle by clearing
+    the pull bookkeeping and flipping the item back to PROPOSED.
+
+    Idempotent and a no-op when no item points at the task. Called from the Task
+    post_save soft-delete receiver (TruePPM Tasks soft-delete, not hard-delete).
+    """
+    item = BacklogItem.objects.filter(pulled_task_id=uuid.UUID(task_id), is_deleted=False).first()
+    if item is None or item.status != BacklogItemStatus.PULLED:
+        return
+    item.status = BacklogItemStatus.PROPOSED
+    item.pulled_task = None
+    item.pulled_at = None
+    item.pulled_by = None
+    # server_version auto-bumps in VersionedModel.save() — omitted from update_fields.
+    item.save(update_fields=["status", "pulled_task", "pulled_at", "pulled_by"])

trueppm_api/apps/projects/backlog_views.py

@@ -0,0 +1,302 @@
+"""Views for the program backlog (ADR-0069 Erratum, #737 / #739).
+
+``BacklogItem`` is a program-scoped CRUD resource nested under a program, plus a
+``pull`` action that converts a PROPOSED item into a project-backlog Task. The
+project-backlog *read* (Task with ``status=BACKLOG``, ``sprint=NULL``) is served
+by the existing ``TaskViewSet`` filters (``?status=BACKLOG&sprint=none``) — no
+separate endpoint is added here.
+
+Permission matrix (ADR-0069 Erratum §4):
+  list / retrieve         — IsProgramMember (Viewer+)
+  create / update / destroy — IsProgramEditor (Team Member+)
+  pull                    — IsProgramEditor **and** write role on the target project
+"""
+
+from __future__ import annotations
+
+from django.contrib.postgres.search import TrigramSimilarity
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.db.models import QuerySet
+from django.shortcuts import get_object_or_404
+from drf_spectacular.utils import OpenApiResponse, extend_schema, inline_serializer
+from rest_framework import mixins, serializers, status, viewsets
+from rest_framework.decorators import action
+from rest_framework.permissions import BasePermission, IsAuthenticated
+from rest_framework.request import Request
+from rest_framework.response import Response
+from rest_framework.serializers import BaseSerializer
+
+from trueppm_api.apps.access.models import Role
+from trueppm_api.apps.access.permissions import (
+    IsProgramEditor,
+    IsProgramMember,
+    IsProgramNotClosed,
+    McpReadableViewMixin,
+    McpScope,
+    _membership_role,
+    assert_project_not_archived,
+)
+from trueppm_api.apps.idempotency.mixins import IdempotencyMixin
+from trueppm_api.apps.projects.backlog_services import (
+    BacklogItemNotPullable,
+    CrossProgramPullError,
+    pull_to_project_backlog,
+)
+from trueppm_api.apps.projects.models import (
+    BacklogItem,
+    BacklogItemStatus,
+    Program,
+    Project,
+)
+from trueppm_api.apps.projects.serializers import BacklogItemSerializer, TaskSerializer
+from trueppm_api.core.request_body import object_body
+
+
+class BacklogItemViewSet(
+    McpReadableViewMixin,
+    IdempotencyMixin,
+    mixins.ListModelMixin,
+    mixins.CreateModelMixin,
+    mixins.RetrieveModelMixin,
+    mixins.UpdateModelMixin,
+    mixins.DestroyModelMixin,
+    viewsets.GenericViewSet[BacklogItem],
+):
+    """CRUD + pull for program backlog items.
+
+    URL: ``/api/v1/programs/<program_pk>/backlog-items/[<pk>/]``
+         ``/api/v1/programs/<program_pk>/backlog-items/<pk>/pull/``
+
+    ``McpReadableViewMixin`` (ADR-0186 §E) additively exposes the list/retrieve
+    reads to a personal ``mcp:read`` API token — it powers the MCP
+    ``list_program_backlog`` tool. Because this viewset overrides
+    ``get_permissions`` with a per-action list, the MCP token guards are appended
+    from that wrapper (via ``mcp_token_guards()``) rather than the mixin's default
+    ``get_permissions``, so no branch — including the write branches — can leak a
+    token past ``TokenReadOnlyMethods`` / ``TokenHasScope`` / ``TokenIsOwnerScoped``.
+    """
+
+    # ADR-0678 (#2482): program-level intake pool. BacklogItem has no project FK,
+    # so the central filter reaches it through the `program` branch — a child
+    # project's opt-out does not withhold intake data the project does not own.
+    mcp_scope = McpScope.AGGREGATE
+
+    serializer_class = BacklogItemSerializer
+
+    def get_permissions(self) -> list[BasePermission]:
+        # ADR-0186 §E: append the read-only MCP token guards around the
+        # action-specific RBAC list so a mcp:read token is confined to safe
+        # methods on every action (no write-branch leak); human auth passes both.
+        return [*self._rbac_permissions(), *self.mcp_token_guards()]
+
+    def _rbac_permissions(self) -> list[BasePermission]:
+        if self.action in ("list", "retrieve"):
+            return [IsAuthenticated(), IsProgramMember(), IsProgramNotClosed()]
+        # create / update / partial_update / destroy / pull all require program
+        # write (Team Member+). The pull action additionally checks project-write
+        # on the resolved target inside the handler.
+        return [IsAuthenticated(), IsProgramEditor(), IsProgramNotClosed()]
+
+    def get_queryset(self) -> QuerySet[BacklogItem]:
+        """Program-scoped backlog.
+
+        The list view layers on item_type / status / tags / ``?q=`` filters and
+        defaults ``status`` to PROPOSED (the active pool). Those filters are
+        **list-only** — detail operations (retrieve / update / destroy) must be
+        able to reach an item in *any* status (e.g. PATCH an item to ARCHIVED,
+        or fetch a PULLED item), so they get the unfiltered program-scoped set.
+        """
+        program_pk = str(self.kwargs["program_pk"])
+        qs = BacklogItem.objects.filter(program_id=program_pk, is_deleted=False).select_related(
+            # pulled_task__project powers the serializer's pulled_task_project_*
+            # wayfinding fields (#1994) without an extra query per pulled row.
+            "pulled_task__project",
+            "created_by",
+            "pulled_by",
+        )
+
+        if self.action != "list":
+            return qs
+
+        item_type = self.request.query_params.get("item_type")
+        if item_type:
+            qs = qs.filter(item_type=item_type)
+
+        # status: explicit value filters; a present-but-empty value means "all";
+        # absent means the default active pool (PROPOSED).
+        if "status" in self.request.query_params:
+            status_filter = self.request.query_params.get("status")
+            if status_filter:
+                qs = qs.filter(status=status_filter)
+        else:
+            qs = qs.filter(status=BacklogItemStatus.PROPOSED)
+
+        # tags: repeatable ?tags=foo&tags=bar — match items carrying ALL given tags.
+        tags = self.request.query_params.getlist("tags")
+        for tag in tags:
+            if tag:
+                qs = qs.filter(tags__contains=[tag])
+
+        # Trigram fuzzy search on title (#739). Combines with the filters above;
+        # an empty/absent q is a no-op (other filters + default ordering apply).
+        #
+        # The FILTER uses the ``%`` operator (``__trigram_similar``) — this is the
+        # form the ``gin_trgm_ops`` GIN index (backlogitem_title_trgm) accelerates,
+        # so search scales as the ADR intends rather than seq-scanning a computed
+        # similarity per row. The ``%`` operator honours pg_trgm's
+        # ``similarity_threshold`` (default 0.3). We additionally annotate the
+        # whole-string similarity and order by it desc so the closest title ranks
+        # first, overriding the model's default priority_rank ordering for searches.
+        q = (self.request.query_params.get("q") or "").strip()
+        if q:
+            qs = (
+                qs.annotate(similarity=TrigramSimilarity("title", q))
+                .filter(title__trigram_similar=q)
+                .order_by("-similarity")
+            )
+
+        return qs
+
+    def _resolve_program(self) -> Program:
+        program = get_object_or_404(Program, pk=self.kwargs["program_pk"], is_deleted=False)
+        # DRF skips has_object_permission on create/custom actions — enforce the
+        # program role gate against the resolved program before any write.
+        self.check_object_permissions(self.request, program)
+        return program
+
+    def perform_create(self, serializer: BaseSerializer[BacklogItem]) -> None:
+        program = self._resolve_program()
+        # status is forced to PROPOSED on create regardless of payload — a new
+        # item always enters the active pool; PULLED/ARCHIVED are reached later
+        # via the pull action / archive PATCH.
+        serializer.save(
+            program=program,
+            created_by=self.request.user,
+            status=BacklogItemStatus.PROPOSED,
+        )
+
+    def perform_destroy(self, instance: BacklogItem) -> None:
+        # Soft-delete so the sync protocol ships a tombstone rather than the row
+        # vanishing silently (VersionedModel contract).
+        instance.soft_delete()
+
+    # Surfaced by the #2840 conformance guard, which scans every module under
+    # ``apps/`` rather than ``views.py`` alone. Every part of the inferred contract
+    # was wrong: the fallback declared a full BacklogItemRequest body (the real
+    # body is ``{"project_id": …}``) and a bare ``200 BacklogItem`` response (the
+    # handler returns ``201`` with a two-key envelope carrying the created Task
+    # *and* the transitioned item).
+    @extend_schema(
+        summary="Pull a backlog item into a project's backlog",
+        request=inline_serializer(
+            name="BacklogItemPullRequest",
+            fields={"project_id": serializers.UUIDField()},
+        ),
+        responses={
+            201: inline_serializer(
+                name="BacklogItemPullResult",
+                fields={
+                    "task": TaskSerializer(),
+                    "backlog_item": BacklogItemSerializer(),
+                },
+            ),
+            400: OpenApiResponse(
+                description="project_id missing, or the target project is not in this program."
+            ),
+            403: OpenApiResponse(
+                description=(
+                    "Caller lacks Team Member+ on the target project, **or** the target "
+                    "project is archived. The archived case is not a role problem and no "
+                    "role clears it — unarchive the project and retry (#3354)."
+                )
+            ),
+            409: OpenApiResponse(description="The item is no longer PROPOSED."),
+        },
+    )
+    @action(detail=True, methods=["post"], url_path="pull")
+    def pull(self, request: Request, program_pk: str, pk: str) -> Response:
+        """Pull a PROPOSED item into a project's backlog (ADR-0069 Erratum §5).
+
+        Body: ``{"project_id": "<uuid>"}``. Creates a Task (status=BACKLOG,
+        sprint=NULL) in the target project and transitions the item to PULLED.
+        Requires program-write (gated by ``get_permissions``) **and** write role
+        on the target project (checked here). Never assigns a sprint.
+
+        Returns ``201`` with the created task and the updated backlog item.
+        ``400`` if project_id is missing / not in this program; ``403`` if the
+        caller lacks project-write **or the target project is archived** (the
+        latter clears for no role — the project must be unarchived); ``409`` if
+        the item is no longer PROPOSED.
+        """
+        # Confirm the program exists and the caller holds program-write.
+        self._resolve_program()
+
+        project_id = object_body(request).get("project_id")
+        if not project_id:
+            return Response(
+                {"detail": "project_id is required."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Resolve the target project, scoped to this program. A project_id that
+        # is not in the program returns 404-as-400 (cross-program pull rejected).
+        try:
+            project = Project.objects.get(pk=project_id, program_id=program_pk, is_deleted=False)
+        except (Project.DoesNotExist, ValueError, DjangoValidationError):
+            return Response(
+                {"detail": "Target project not found in this program."},
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+
+        # Project-level write gate: program-write alone is not enough to drop a
+        # Task into a project — the caller must also be Team Member+ on it.
+        role = _membership_role(request, project.pk)
+        if role is None or role < Role.MEMBER:
+            return Response(
+                {"detail": "You need at least Team Member role on the target project."},
+                status=status.HTTP_403_FORBIDDEN,
+            )
+        # Archived target projects take no writes, and a pull creates a Task (#3354).
+        # `IsProgramNotClosed` in `get_permissions` gates the *program*; nothing was
+        # checking the project's own lifecycle. `IsProjectNotArchived` cannot cover
+        # this route: the target project comes from the request body, so there is no
+        # `project_pk` kwarg for `has_permission` and `get_object()` returns the
+        # `BacklogItem` — the same blind spot as `ProjectTemplateViewSet.apply`, and
+        # it needs the same explicit assert. Placed after the role check so a caller
+        # without project-write still gets the role refusal first.
+        assert_project_not_archived(project.pk)
+
+        try:
+            task = pull_to_project_backlog(item_id=str(pk), project=project, actor=request.user)
+        except BacklogItem.DoesNotExist:
+            return Response(
+                {"detail": "Backlog item not found."},
+                status=status.HTTP_404_NOT_FOUND,
+            )
+        except CrossProgramPullError as exc:
+            # False positive: domain exception with a curated, client-safe message
+            # (single-program pull boundary, ADR-0069) — no server internals.
+            return Response(
+                {"detail": str(exc)},  # codeql[py/stack-trace-exposure]
+                status=status.HTTP_400_BAD_REQUEST,
+            )
+        except BacklogItemNotPullable as exc:
+            # False positive: curated domain message (item no longer PROPOSED).
+            return Response(
+                {"detail": str(exc)},  # codeql[py/stack-trace-exposure]
+                status=status.HTTP_409_CONFLICT,
+            )
+
+        # Re-fetch with the FK joins the serializer reads (pulled_task__project,
+        # created_by, pulled_by) so the pull response doesn't fire lazy per-FK
+        # queries — including the pulled_task_project_* wayfinding fields (#1994).
+        item = BacklogItem.objects.select_related(
+            "pulled_task__project", "created_by", "pulled_by"
+        ).get(pk=pk)
+        return Response(
+            {
+                "task": TaskSerializer(task).data,
+                "backlog_item": BacklogItemSerializer(item).data,
+            },
+            status=status.HTTP_201_CREATED,
+        )