trueppm-api 0.4.0__py3-none-any.whl

trueppm_api/apps/projects/management/commands/shift_sample_dates.py

@@ -0,0 +1,120 @@
+"""Re-anchor bundled sample programs to today (#3481, ADR-1175).
+
+Usage::
+
+    python manage.py shift_sample_dates [--program <id>] [--dry-run]
+
+The command-line half of the "Shift dates to today" banner action. It exists so a
+long-lived demo deployment can keep its sample current from a scheduled job it
+owns — a Kubernetes CronJob alongside the existing demo-seed Job, say — rather
+than every self-hosted install acquiring a Celery beat that silently rewrites
+rows nobody asked it to touch.
+
+That is the deliberate shape of ADR-1175 Decision 1: **no global beat ships**. An
+operator who wants automatic re-anchoring opts into it visibly, in their own
+manifests, where a failure is theirs to see.
+
+Idempotent, like the endpoint: a sample already within a week of today reports
+"already current" and writes nothing, so running this nightly is safe.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.core.management.base import BaseCommand, CommandError
+
+from trueppm_api.apps.projects.models import Program, Project
+from trueppm_api.apps.projects.seed.reanchor import (
+    NoAnchorRecorded,
+    NotASampleProgram,
+    shift_sample_dates,
+    whole_week_delta,
+)
+
+
+class Command(BaseCommand):
+    help = "Shift bundled sample programs' dates forward to today."
+
+    def add_arguments(self, parser: Any) -> None:
+        parser.add_argument(
+            "--program",
+            help="Shift only this program id. Default: every sample program on the install.",
+        )
+        parser.add_argument(
+            "--dry-run",
+            action="store_true",
+            help="Report what would move without writing anything.",
+        )
+
+    def handle(self, *args: Any, **options: Any) -> None:
+        from django.utils import timezone
+
+        programs = self._resolve_programs(options.get("program"))
+        if not programs:
+            self.stdout.write("No sample programs found; nothing to do.")
+            return
+
+        today = timezone.localdate()
+        for program in programs:
+            label = f"{program.name!r} ({program.pk})"
+            if options["dry_run"]:
+                self._report_dry_run(program, label, today)
+            else:
+                self._shift(program, label)
+
+    def _report_dry_run(self, program: Program, label: str, today: Any) -> None:
+        # Reported from the same helper the shift uses, so the dry run
+        # cannot disagree with the real thing about how far it would move.
+        if program.sample_anchor_date is None:
+            self.stdout.write(
+                self.style.WARNING(f"  {label}: no anchor recorded — reload it instead.")
+            )
+            return
+        days = whole_week_delta(program.sample_anchor_date, today)
+        if days == 0:
+            self.stdout.write(f"  {label}: already current.")
+        else:
+            self.stdout.write(f"  {label}: would move forward {days} days.")
+
+    def _shift(self, program: Program, label: str) -> None:
+        try:
+            report = shift_sample_dates(program)
+        except NotASampleProgram as exc:
+            # Only reachable via --program: the default query already filters
+            # to programs holding a sample project.
+            raise CommandError(f"{label}: {exc}") from exc
+        except NoAnchorRecorded:
+            self.stdout.write(
+                self.style.WARNING(
+                    f"  {label}: loaded before date shifting existed, so its original "
+                    f"dates are not recorded. Remove and reload it to get current dates."
+                )
+            )
+            return
+
+        if report.shifted:
+            self.stdout.write(
+                self.style.SUCCESS(
+                    f"  {label}: moved forward {report.days} days — "
+                    f"{report.rows_shifted} records across {report.projects} project(s). "
+                    f"Schedules re-queued."
+                )
+            )
+        else:
+            self.stdout.write(f"  {label}: already current.")
+
+    def _resolve_programs(self, program_id: str | None) -> list[Program]:
+        if program_id:
+            program = Program.objects.filter(pk=program_id).first()
+            if program is None:
+                raise CommandError(f"No program with id {program_id!r}.")
+            return [program]
+        # Sample-ness lives on Project, not Program — a program is demo data when
+        # it holds at least one is_sample project (the same test remove_sample and
+        # the banner use).
+        return list(
+            Program.objects.filter(
+                pk__in=Project.objects.filter(is_sample=True, is_deleted=False).values("program")
+            ).order_by("name")
+        )

trueppm_api/apps/projects/mcp_settings.py

@@ -0,0 +1,305 @@
+"""Instance → Workspace → Program → Project MCP read-consent resolution (ADR-0678, #2482).
+
+One inheritable setting governs whether an MCP/agent token may read a project's
+data: ``mcp_enabled``. The Workspace root is non-null (default ``True``); Program
+and Project are nullable, where ``None`` means *no opinion* — **never "yes"**.
+
+**The cascade is restrictive-only (AND), not override.** This is the one place
+this module deliberately diverges from the ADR-0135/0144/0151/0153/0510 settings
+family, and the divergence is the point::
+
+    effective(project) = settings.TRUEPPM_MCP_ENABLED     # ADR-0497 instance switch
+                     AND workspace.mcp_enabled
+                     AND (program.mcp_enabled is not False)
+                     AND (project.mcp_enabled is not False)
+
+Any scope may deny for itself and everything beneath it; **no scope may grant over
+another scope's denial**. For sharing and attachments a workspace ``ENFORCE`` lock
+is a security *ceiling* and pointing it downward is coherent. For a **consent**
+switch it is not: an org-level lock that could force MCP back on for a team is
+precisely the *"consent that only an admin can grant or revoke on the team's
+behalf is consent in name only"* objection (#2415) this control exists to answer.
+
+Consequently there is **no** ``mcp_override_policy`` field and **no** Enterprise
+enforcement-provider seam here, unlike :mod:`~trueppm_api.apps.projects.attachment_policy`.
+That asymmetry is deliberate, not an oversight. Enterprise governance keeps the
+only lever that is coherent for a consent control — turning MCP off at the
+workspace scope, org-wide — which the AND already honors.
+
+The one policy knob that does exist, ``TRUEPPM_MCP_PROGRAM_EXPORT_POLICY``
+(:func:`program_export_policy`, #3014), is **operator-level and not a scope in this
+cascade**. It answers a question the AND above cannot: a program-level *bulk export*
+carries every member project's rows verbatim in one artifact that cannot be narrowed,
+so the choice is serve-or-refuse rather than filter. Keeping it in deployment
+settings rather than on ``Workspace`` or ``Program`` is what stops it from becoming
+the tenant-scope override this module refuses — an operator is the person running
+the server, not a scope above the team inside it.
+
+Resolution is computed-on-read (ADR-0108); there is no denormalized effective
+column to keep in sync. Clients read the serializer's ``effective_mcp_enabled`` /
+``inherited_mcp_enabled`` fields and never re-implement this precedence.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from django.db.models import QuerySet
+    from rest_framework.request import Request
+
+    from trueppm_api.apps.projects.models import Program, Project
+    from trueppm_api.apps.workspace.models import Workspace
+
+#: The single inheritable field name — identical on Workspace (non-null root),
+#: Program, and Project (nullable "no opinion").
+MCP_CONSENT_FIELD = "mcp_enabled"
+
+
+def _instance_enabled() -> bool:
+    """The ADR-0497 instance-wide kill switch, read at call time.
+
+    Read through ``getattr`` at call time (not import time) so ``override_settings``
+    and a live operator env change both take effect, matching ``McpInstanceEnabled``.
+    """
+    from django.conf import settings
+
+    return bool(getattr(settings, "TRUEPPM_MCP_ENABLED", True))
+
+
+def _program_of(obj: Program | Project) -> Program | None:
+    """The program scope above ``obj`` (a Project's program), or None."""
+    from trueppm_api.apps.projects.models import Program
+
+    if not isinstance(obj, Program) and getattr(obj, "program_id", None):
+        return obj.program
+    return None
+
+
+def resolve_mcp_enabled(
+    obj: Program | Project,
+    *,
+    workspace: Workspace | None = None,
+    include_instance: bool = True,
+) -> bool:
+    """Resolve effective MCP read consent for a program or project.
+
+    ANDs every scope: instance → workspace → program → project. A ``None`` at the
+    program or project scope contributes nothing (no opinion); only an explicit
+    ``False`` denies.
+
+    ``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.
+
+    ``include_instance=False`` omits the ADR-0497 instance switch, for callers that
+    want the *team's* answer alone — the settings UI shows the team's decision even
+    on an instance where MCP is globally off, so the two switches stay legible as
+    separate facts rather than collapsing into one confusing "off".
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if include_instance and not _instance_enabled():
+        return False
+
+    if workspace is None:
+        workspace = Workspace.load()
+    if not workspace.mcp_enabled:
+        return False
+
+    return _parent_and_own_enabled(obj)
+
+
+def resolve_inherited_mcp_enabled(
+    obj: Program | Project,
+    *,
+    workspace: Workspace | None = None,
+) -> bool:
+    """Value ``obj`` would resolve to if its own override were cleared to *no opinion*.
+
+    Drives the settings "Inherit (On/Off)" affordance — it deliberately skips
+    ``obj``'s own value and resolves from the parent scopes up. The instance switch
+    is excluded for the same legibility reason as
+    :func:`resolve_mcp_enabled`'s ``include_instance=False``.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+    if not workspace.mcp_enabled:
+        return False
+
+    program = _program_of(obj)
+    return not (program is not None and program.mcp_enabled is False)
+
+
+def _parent_and_own_enabled(obj: Program | Project) -> bool:
+    """AND of the program scope (if any) and ``obj``'s own value.
+
+    Tri-state: the test is ``is False``, never truthiness — ``None`` is "no
+    opinion" and must not be read as a denial.
+    """
+    program = _program_of(obj)
+    if program is not None and program.mcp_enabled is False:
+        return False
+    return obj.mcp_enabled is not False
+
+
+def is_mcp_readable(
+    obj: Program | Project,
+    *,
+    workspace: Workspace | None = None,
+) -> bool:
+    """The single enforcement predicate: may an agent token read ``obj``'s data?"""
+    return resolve_mcp_enabled(obj, workspace=workspace)
+
+
+def mcp_opted_out_project_ids() -> QuerySet[Any]:
+    """Project ids closed to agent reads by *their own or their program's* denial.
+
+    Returns a lazy values-list queryset so callers can use it directly as an
+    ``__in`` subquery without a second round trip. Deliberately does **not**
+    consider the workspace or instance switch: those are all-or-nothing and are
+    short-circuited by the caller (see :func:`mcp_reads_globally_disabled`) rather
+    than expanded into a project-id set, which at scale would mean listing every
+    project on the instance.
+    """
+    from django.db.models import Q
+
+    from trueppm_api.apps.projects.models import Project
+
+    return Project.objects.filter(Q(mcp_enabled=False) | Q(program__mcp_enabled=False)).values_list(
+        "pk", flat=True
+    )
+
+
+#: Policy values for :data:`django.conf.settings.TRUEPPM_MCP_PROGRAM_EXPORT_POLICY`.
+PROGRAM_EXPORT_WITHHOLD = "withhold"
+PROGRAM_EXPORT_ALLOW = "allow"
+PROGRAM_EXPORT_POLICIES = frozenset({PROGRAM_EXPORT_WITHHOLD, PROGRAM_EXPORT_ALLOW})
+
+
+def program_export_policy() -> str:
+    """The operator's program-bulk-export policy, read at call time (#3014).
+
+    Unrecognized values fall back to ``withhold`` rather than raising: this is read
+    on a request path, and a typo in an env var must not turn a consent control off
+    by accident. A boot-time check (``core.checks``) surfaces the typo loudly so the
+    fallback is a safety net rather than a place mistakes go to hide.
+    """
+    from django.conf import settings
+
+    value = str(getattr(settings, "TRUEPPM_MCP_PROGRAM_EXPORT_POLICY", PROGRAM_EXPORT_WITHHOLD))
+    normalized = value.strip().lower()
+    return normalized if normalized in PROGRAM_EXPORT_POLICIES else PROGRAM_EXPORT_WITHHOLD
+
+
+def program_export_withheld_from_agents(program: Program) -> bool:
+    """Whether an agent token must be refused this program's bulk export (#3014).
+
+    A program-level bulk export — the sync JSON seed (``GET /programs/{id}/export/``)
+    and the async ``.tar.gz`` bundle — carries **every member project's data
+    verbatim**. The mixin's ``Program`` branch in ``_mcp_filter_queryset`` governs
+    only ``program.mcp_enabled``, so without this a child project's explicit "no" is
+    silently bypassed by reading the parent's export instead. Read through the
+    project's own endpoints, the same rows are withheld.
+
+    **Why withhold rather than narrow.** Neither surface can honestly serve a
+    subset. The ``.tar.gz`` is built asynchronously and streamed from storage as
+    opaque bytes, so at download time there is nothing left to filter — and because
+    ``TokenReadOnlyMethods`` refuses an agent token on POST, the archive was always
+    built *for a human*, so filtering at build time cannot see the eventual agent
+    reader either. The sync seed *could* be narrowed at request time, but a seed is
+    a re-import artifact: handing back something shaped like the program that
+    quietly is not the program is worse than refusing. So the lever is
+    serve-or-refuse, and the policy setting chooses which.
+
+    Returns ``False`` for the ``allow`` policy, and for a program with no opted-out
+    member project — the common case, answered with one ``EXISTS`` query.
+    """
+    if program_export_policy() == PROGRAM_EXPORT_ALLOW:
+        return False
+
+    from trueppm_api.apps.projects.models import Project
+
+    # Evaluated against the program's CURRENT member projects, not against a
+    # manifest of what the archive actually contains — ``ProgramExportJob`` records
+    # no such manifest. That makes this very slightly over-inclusive (a project that
+    # opted out after the bundle was built still withholds it) and never
+    # under-inclusive, which is the correct direction for a consent control.
+    return Project.objects.filter(
+        program_id=program.pk, pk__in=mcp_opted_out_project_ids()
+    ).exists()
+
+
+def mcp_reads_globally_disabled(*, workspace: Workspace | None = None) -> bool:
+    """True when a scope above every project denies — instance or workspace.
+
+    Lets the enforcement point answer "deny everything" without materializing a
+    project-id set.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if not _instance_enabled():
+        return True
+    if workspace is None:
+        workspace = Workspace.load()
+    return not workspace.mcp_enabled
+
+
+def mcp_excluded_project_ids(request: Request) -> QuerySet[Any] | None:
+    """Project ids this request must NOT read, or ``None`` when nothing is withheld.
+
+    The exclusion-shaped companion to :func:`mcp_visible_project_ids`, for the
+    program-level services (``compute_program_schedule``,
+    ``compute_program_rollup``) whose natural seam is "drop these projects" rather
+    than "keep these". Returns ``None`` for a human caller and for the common case
+    where no project on the instance has opted out, so those services keep their
+    existing query plan untouched on every normal request.
+
+    A workspace/instance-level denial is not expanded here: those are caught by
+    :class:`~trueppm_api.apps.access.permissions.McpProjectEnabled`, which 403s the
+    request before any service runs.
+    """
+    from trueppm_api.apps.projects.models import is_agent_token
+
+    if not is_agent_token(getattr(request, "auth", None)):
+        return None  # Human JWT/Session or the owner's own full-access PAT (#2877).
+
+    opted_out = mcp_opted_out_project_ids()
+    if not opted_out.exists():
+        return None
+    return opted_out
+
+
+def mcp_visible_project_ids(request: Request) -> QuerySet[Any] | None:
+    """Project ids this request may read, or ``None`` when no filtering is needed.
+
+    The primitive the hand-built aggregate views (``/me/search``, ``/me/work/``,
+    workspace assets) and the program-level rollups intersect against. Returns:
+
+    * ``None`` — the caller is not an agent token (a human, or a ``legacy:full``
+      personal access token, which is a person's own credential and not subject to
+      agent consent — #2877), or no project on the instance has opted out. Callers
+      skip filtering entirely; this is the case on virtually every instance, so the
+      common path costs one cheap ``EXISTS``.
+    * an empty queryset — a scope above every project denies (instance or
+      workspace off), so nothing is visible.
+    * a values-list queryset of readable project ids otherwise.
+
+    why a *positive* id set rather than an exclusion list: the aggregate views
+    already join through several project relations, and an ``__in`` against the
+    allowed set composes with their existing membership filters without needing
+    each call site to reason about NULL semantics.
+    """
+    from trueppm_api.apps.projects.models import Project, is_agent_token
+
+    if not is_agent_token(getattr(request, "auth", None)):
+        return None  # Human JWT/Session or the owner's own full-access PAT (#2877).
+
+    if mcp_reads_globally_disabled():
+        return Project.objects.none().values_list("pk", flat=True)
+
+    opted_out = mcp_opted_out_project_ids()
+    if not opted_out.exists():
+        return None  # Fast path: nothing opted out anywhere on the instance.
+    return Project.objects.exclude(pk__in=opted_out).values_list("pk", flat=True)

trueppm_api/apps/projects/methodology.py

@@ -0,0 +1,178 @@
+"""Workspace → Program → Project methodology resolution (ADR-0107, issue 955).
+
+The planning *methodology* (``AGILE`` / ``WATERFALL`` / ``HYBRID``) is the
+"experience preset" that hides one workflow's chrome from the other (ADR-0041 —
+the API surface and CPM substrate are unchanged; only tab visibility shifts). It
+is set at three scopes; the *effective* methodology a project displays 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_methodology``; they never re-implement this precedence.
+
+**Crucial difference from iteration_label / sharing inheritance:** methodology is
+NOT-NULL on every scope (Workspace/Program/Project each always carry a concrete
+value — there is no null "inherit" sentinel). So inheritance is **policy-driven**,
+not override-presence driven. The single switch is the workspace's
+``methodology_override_policy``:
+
+- ``SUGGEST`` (default) → each scope's own ``methodology`` is honored; the
+  workspace default merely pre-fills new projects. Precedence:
+  project.methodology → program.methodology → workspace.methodology.
+- ``INHERIT`` → the workspace default wins for every scope; the per-scope picker
+  is read-only ("Inherited from workspace").
+- ``ENFORCE`` → the workspace default is mandatory and the per-scope override is
+  blocked. ``ENFORCE`` is an Enterprise capability (trueppm-enterprise#144); OSS
+  ships the neutral hook below and registers no provider, so ``ENFORCE`` degrades
+  to ``SUGGEST`` (no lock — the per-scope override wins and the methodology PATCH
+  is allowed).
+
+OSS never imports enterprise. trueppm-enterprise registers a provider in its
+``AppConfig.ready()`` — the integrations-registry idiom (ADR-0029/0049), mirroring
+``iteration_label.register_terminology_enforcement_provider`` and
+``sharing_settings.register_sharing_enforcement_provider``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from trueppm_api.apps.projects.models import Methodology
+from trueppm_api.core.extension_providers import guard_single_provider
+
+if TYPE_CHECKING:
+    from trueppm_api.apps.projects.models import Program, Project
+    from trueppm_api.apps.workspace.models import Workspace
+
+#: System backstop when nothing up the chain sets a methodology. Mirrors the
+#: model defaults (HYBRID shows every tab — the safe, lossless default).
+DEFAULT_METHODOLOGY = Methodology.HYBRID
+
+# Enterprise registers a zero-arg predicate that returns True when methodology
+# enforcement is licensed/active. OSS leaves it None → enforcement inactive, so
+# a workspace ENFORCE policy never locks downstream overrides in the community
+# edition.
+_ENFORCEMENT_PROVIDER: Callable[[], bool] | None = None
+
+
+def register_methodology_enforcement_provider(provider: Callable[[], bool] | None) -> None:
+    """Register (or clear) the methodology-enforcement provider. Enterprise calls this."""
+    global _ENFORCEMENT_PROVIDER
+    _ENFORCEMENT_PROVIDER = guard_single_provider(
+        _ENFORCEMENT_PROVIDER, provider, "methodology enforcement"
+    )
+
+
+def methodology_enforcement_active() -> bool:
+    """True only when an enterprise provider is registered AND reports active.
+
+    OSS has no provider → always False, so a workspace ``ENFORCE`` policy never
+    locks downstream methodology overrides in the community edition.
+    """
+    return _ENFORCEMENT_PROVIDER is not None and bool(_ENFORCEMENT_PROVIDER())
+
+
+def methodology_override_locked(workspace: Workspace) -> bool:
+    """Whether per-scope methodology overrides are locked to the workspace default.
+
+    True under ``INHERIT`` (always — the affordance is hidden by design) or under
+    ``ENFORCE`` *with* an active enterprise provider. ``SUGGEST`` (and OSS
+    ``ENFORCE`` with no provider) returns False, so the per-scope override is
+    honored and editable. This is the single predicate the serializer and the
+    write-permission gate both consult, so resolution and enforcement can never
+    drift apart.
+    """
+    from trueppm_api.apps.workspace.models import TermOverridePolicy
+
+    policy = workspace.methodology_override_policy
+    if policy == TermOverridePolicy.INHERIT:
+        return True
+    if policy == TermOverridePolicy.ENFORCE:
+        return methodology_enforcement_active()
+    return False
+
+
+def resolve_effective_methodology(
+    obj: Program | Project, *, workspace: Workspace | None = None
+) -> str:
+    """Resolve the effective methodology a program or project should display.
+
+    ``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.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+
+    if methodology_override_locked(workspace):
+        # INHERIT / active ENFORCE: the workspace default wins regardless of any
+        # lower-scope value.
+        return workspace.methodology or DEFAULT_METHODOLOGY
+
+    # SUGGEST (or OSS ENFORCE with no provider): each scope's own value wins, then
+    # the program tier, then the workspace default. Every value is non-null, so
+    # this short-circuits at the object itself in the common case.
+    from trueppm_api.apps.projects.models import Program
+
+    own = obj.methodology
+    if own:
+        return own
+    program = obj.program if (not isinstance(obj, Program) and obj.program_id) else None
+    program_value = program.methodology if program else None
+    return program_value or workspace.methodology or DEFAULT_METHODOLOGY
+
+
+def resolve_new_project_methodology(
+    program: Program | None, *, workspace: Workspace | None = None
+) -> str:
+    """Methodology a *new* project starts with when the caller did not choose one.
+
+    The resolver above is computed-on-read, but a project's ``methodology`` column
+    is NOT-NULL with a HYBRID model default — so a project created without an
+    explicit value is *stored* as HYBRID and, under ``SUGGEST``, stays HYBRID at
+    read time no matter what its program or workspace says (the project's own
+    value wins the chain). The "workspace default pre-fills new projects" and
+    "new projects in this program start with its methodology" promises are
+    therefore only true if whoever creates the project seeds the stored value.
+    The interactive New-project sheet does that client-side
+    (``deriveStartSheetMethodology``: ``program.effective_methodology`` if a
+    program is selected, else the workspace default); this is the server-side
+    equivalent for every other door a project enters through — the MS Project
+    create-from-import endpoint today — so the delivery model a project lands
+    with cannot depend on which door it came through (#3432).
+
+    Under an active lock the answer is the workspace default either way, which is
+    also exactly what the effective resolver will report for the new project.
+    """
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+    if program is not None:
+        return resolve_effective_methodology(program, workspace=workspace)
+    return workspace.methodology or DEFAULT_METHODOLOGY
+
+
+def resolve_inherited_methodology(
+    obj: Program | Project, *, workspace: Workspace | None = None
+) -> str:
+    """Methodology ``obj`` would display if its own override were ignored.
+
+    Drives the settings "Inherited from workspace (X)" affordance — it skips
+    ``obj``'s own value and resolves from the parent scope up. A Program's parent
+    is the workspace; a Project's parent is its program (whose own value resolves
+    up to the workspace) or, standalone, the workspace. Under an active lock the
+    inherited value is the (mandatory) workspace default.
+    """
+    from trueppm_api.apps.projects.models import Program
+    from trueppm_api.apps.workspace.models import Workspace
+
+    if workspace is None:
+        workspace = Workspace.load()
+
+    if methodology_override_locked(workspace):
+        return workspace.methodology or DEFAULT_METHODOLOGY
+
+    program = obj.program if (not isinstance(obj, Program) and obj.program_id) else None
+    program_value = program.methodology if program else None
+    return program_value or workspace.methodology or DEFAULT_METHODOLOGY

trueppm_api/apps/projects/migration_helpers.py

@@ -0,0 +1,75 @@
+"""Shared helper for the repo's ``CREATE INDEX CONCURRENTLY`` migrations (#4357).
+
+``CREATE INDEX CONCURRENTLY`` does not roll back on failure the way an ordinary
+DDL statement does: if the build is interrupted partway through, PostgreSQL
+leaves the index present but marked ``INVALID`` (the planner ignores it, but
+every write still pays to maintain it). Under `migrate_locked` at
+``replicaCount >= 2`` (the shipped default), every pod's init container races
+an advisory lock for the one migration run; if the lock-holding pod dies
+mid-build (OOM, eviction, node drain), the next pod to win the lock reruns the
+*same* migration. The `IF NOT EXISTS` guard on the `CREATE INDEX CONCURRENTLY`
+sees an index of that name already present, skips it, and the migration is
+recorded applied — so the index is permanently INVALID and unused by the
+planner, with nothing surfacing an error.
+
+This module extracts the repair as a function so a test can call it directly
+without importing a migration module by name, which a squash would delete
+(CLAUDE.md migration rule 3) — the same pattern `projects.backfill` uses for
+0148's repair step.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.db import migrations
+
+
+def repair_invalid_concurrent_index(connection: Any, index_name: str) -> None:
+    """Drop ``index_name`` with ``DROP INDEX CONCURRENTLY`` if it is INVALID.
+
+    No-op when the index does not exist, or exists and is valid — safe to run
+    ahead of every ``CREATE INDEX CONCURRENTLY IF NOT EXISTS`` build of the same
+    name, on every migrate, not just a crash-recovery run.
+
+    ``DROP INDEX CONCURRENTLY`` cannot run inside a transaction block or a
+    ``DO`` block (PostgreSQL executes a ``DO`` body as a single implicit
+    transaction), so this takes a bare connection and issues the statement
+    directly over a cursor — the caller must be a ``RunPython`` operation in an
+    ``atomic = False`` migration, matching the forward build it precedes.
+    """
+    with connection.cursor() as cursor:
+        cursor.execute(
+            "SELECT 1 FROM pg_class c "
+            "JOIN pg_index i ON i.indexrelid = c.oid "
+            "WHERE c.relname = %s AND NOT i.indisvalid",
+            [index_name],
+        )
+        if cursor.fetchone() is not None:
+            # `index_name` is always a hardcoded module-level constant from the
+            # calling migration (see repair_invalid_concurrent_index_op below),
+            # never request- or user-derived input — DDL identifiers can't be
+            # bound as query parameters, so quoting is the only option anyway.
+            # nosemgrep: formatted-sql-query,sqlalchemy-execute-raw-query
+            cursor.execute(f'DROP INDEX CONCURRENTLY IF EXISTS "{index_name}";')
+
+
+def repair_invalid_concurrent_index_op(index_name: str) -> migrations.RunPython:
+    """Build the ``RunPython`` migration operation wrapping the repair above.
+
+    Place this immediately before the existing
+    ``CREATE INDEX CONCURRENTLY IF NOT EXISTS`` ``RunSQL`` operation for the
+    same index name. The reverse is a no-op: tearing an INVALID index back down
+    is not meaningful on a rollback, and the forward build that follows this
+    operation already makes the index valid again on the next `migrate`.
+
+    ``atomic=False`` is passed explicitly (on top of the migration's own
+    ``atomic = False``) so Django's executor never wraps this operation in an
+    implicit transaction on a backend where that would otherwise happen — see
+    ``Migration.apply()``'s ``atomic_operation`` check.
+    """
+
+    def _forward(apps: Any, schema_editor: Any) -> None:
+        repair_invalid_concurrent_index(schema_editor.connection, index_name)
+
+    return migrations.RunPython(_forward, migrations.RunPython.noop, atomic=False)