[BE] Build endpoint for removing a Competency Criterion

Blocked by: #613 (the CBE data model, including StudentCompetencyCriteriaGroupStatus, which this ticket's cascade logic queries), #665 (creates the CompetencyCriterion rows this ticket removes — resolving or creating the group hierarchy as needed via resolve_or_create_leaf_group()/resolve_supplied_leaf_group(), there's no separate group-creation endpoint — plus the REST scaffolding and openedx-platform wiring this ticket relies on), and the archived-field ticket (no GitHub issue yet — adds archived to both CompetencyCriteriaGroup and CompetencyCriterion in one migration, so this ticket and #675 don't have to race to add it themselves).

Repo: openedx-core, single-repo. No openedx-platform changes — this ticket's route registers inside the same rest_api/v1/urls.py that #665 wires into Studio.

Use Case

As a Platform Administrator, I want to remove a single Competency Criterion (a gradeable-subsection association) from a Competency Criteria Group, so that I can correct or retire a mastery rule without having to rebuild the whole group, while learner progress already recorded against that criterion remains intact and auditable.

Description

Current state

No endpoint exists today to remove a CompetencyCriterion. Per ADR 0002 Decision 7, a CompetencyCriterion (table CompetencyCriteria) may be hard-deleted only while no StudentCompetencyCriteriaStatus row references it; once one exists, the criterion must be retired by archiving rather than deleting, and existing learner statuses are retained unchanged. The same delete protection applies one level up: CompetencyCriteriaGroup cannot be hard-deleted while a StudentCompetencyCriteriaGroupStatus row references it, or while it still holds any row (active or archived) underneath it. Per ADR 0003 Decision 4, if the criterion is already in use by learner status, the authoring UI must warn before the change is applied — this ticket's endpoint is the mechanism that enforces the actual archive-vs-delete branch; the UI-side warning and confirmation step is out of scope here (a frontend concern).

Requested change

A new endpoint, nested under the existing criterion's group, that removes a CompetencyCriterion:

• Resolves the criterion from the URL (group_id and criterion_id); 404 if the criterion doesn't exist, or exists but does not belong to the given group_id.
• Checks whether any StudentCompetencyCriteriaStatus row references this criterion.
  • If none exists: hard-deletes the CompetencyCriterion row.
  • If any exists: sets archived=True on the row instead (no hard delete), leaving it in place for learner-status traceability.
• On a hard-delete, also removes the underlying oel_tagging_objecttag row, but only if no other CompetencyCriterion still references it.
  • Per ADR 0002's own worked example, one ObjectTag can be referenced by multiple CompetencyCriterion rows (the same tagged assignment used in two different groups); if another criterion still references it, the tagging association is left untouched.
  • Assumption: removing the last criterion referencing an ObjectTag removes the ObjectTag itself, un-tagging the content, rather than leaving it in place with no criterion behind it for the author to clean up separately in the tagging UI.
  • This only removes the ObjectTag. The underlying Tag (the competency definition itself) is never deleted; it continues to exist in the taxonomy regardless.
• On the archive path, the ObjectTag is never touched. This isn't optional: ADR 0002 Decision 7 extends the same learner-status delete protection to oel_tagging_objecttag, so deleting it while an archived criterion still references it would violate the ADR (and risks cascading away the row being preserved, or orphaning its reference, depending on the FK's on_delete).
  • Practical effect: a retired criterion's tag can still appear associated with the content wherever the tagging system surfaces object tags, effectively demoting it from a competency tag to a regular tag. Whether that specifically surfaces on the Course Outline page depends on a separate open question outside the scope of this Github Issue about whether competency tags should display on the Course Outline page at all (that page is out of MVP scope); either way, the tag stays visible in the tagging system's own views.
  • Accepted for MVP: hard-delete, the higher-frequency path during authoring, already removes the association cleanly. Revisit only if not removing the ObjectTag association on the archive path causes real author confusion post-launch.
• Removing a criterion can leave its parent group, and potentially several ancestor groups above it, with no remaining active content. This endpoint walks the ancestor chain and resolves each level, so no empty group is ever left persisted, per ADR 0002 Decision 2 ("backend validation must reject" persisted empty groups):
  • Starting from the removed/archived criterion's immediate group, and continuing upward through parent_id for as long as a level changes state:
    • If the triggering event below was an archive (the criterion, or an ancestor group, was archived rather than removed): if this group has no remaining non-archived children, archive this group too, then continue the walk one level up, again checking for non-archived children.
    • If the triggering event below was a hard-delete: if this group has no children left at all, hard-delete it too (unless a StudentCompetencyCriteriaGroupStatus row references it directly, in which case archive it instead per the same delete-protection rule that already applies to criteria) and continue the walk one level up as a hard-delete event. If this group's only remaining children are archived, archive this group instead and continue the walk one level up, now as an archive event. If this group still has at least one non-archived child, stop.
  • This matches what the frontend already assumes: the #709/#710 frontend tickets document #674 (this ticket) as cascading an emptied group away server-side, and both rely on the existing "zero real groups → placeholder" fallback (#671/#672) to keep the page renderable even if the walk empties the competency's entire tree.
• Requires oel_tagging.can_tag_object: studio write access to the criterion's course plus taxonomy view access on the competency's taxonomy, checked inline via has_perm() inside delete_competency_criterion(), the same pattern #665 uses in associate_competency_criterion(), not a DRF permission class.
• Is idempotent for an already-archived criterion: a repeat DELETE on an archived row returns the same 200 response rather than a 404 or error, since the row still exists and is already in its terminal state. A repeat DELETE on a hard-deleted (now-gone) row returns 404, since the row is genuinely gone.

Explicitly out of scope

• Removing or archiving a CompetencyCriteriaGroup directly (#675).
• A general-purpose "reject empty groups" validation applied to other write paths (e.g. group creation); this ticket only prevents empty groups via the cascade walk on its own removal path.
• Touching an oel_tagging_objecttag row still referenced by another CompetencyCriterion — shared references are always preserved.
• Any UI, including the in-use warning/confirmation flow ADR 0003 Decision 4 requires in Studio.
• Updating rule_type_override/rule_payload_override/competency_rule_profile_id on an existing criterion (that's an edit, not a removal — a separate ticket if needed).
• Listing or retrieving criteria (a separate GET/list ticket).

Acceptance Criteria

These scenarios are verifiable via Postman.

Scenario: Hard-delete a criterion with no learner status
  Given a CompetencyCriterion exists under a group, with no StudentCompetencyCriteriaStatus row referencing it
  And the requesting user has studio write access to the criterion's course and view access to the competency's taxonomy
  When a DELETE request is sent to the remove-criterion endpoint for that criterion's group_id and criterion_id
  Then the response returns status code 200
  And the response body includes "id" matching the removed criterion and "archived" as false
  And a subsequent DELETE to the same URL returns status code 404

Scenario: Archive instead of hard-delete when learner status exists
  Given a CompetencyCriterion exists and a StudentCompetencyCriteriaStatus row references it
  When a DELETE request is sent to the remove-criterion endpoint for that criterion
  Then the response returns status code 200
  And the response body includes "id" matching the criterion and "archived" as true
  And the CompetencyCriterion row still exists in the database with archived=true

Scenario: Repeat removal of an already-archived criterion is idempotent
  Given a CompetencyCriterion was previously archived via this endpoint
  When a DELETE request is sent again to the same criterion's URL
  Then the response returns status code 200
  And the response body is unchanged ("archived" still true)

Scenario: A shared tagged-object association survives when another criterion still references it
  Given a gradeable subsection is tagged with a competency and referenced by two CompetencyCriterion rows in two different groups
  When a DELETE request removes one of those two CompetencyCriterion rows
  Then the response returns status code 200
  And the other CompetencyCriterion row referencing the same oel_tagging_objecttag is unaffected
  And the underlying oel_tagging_objecttag row still exists

Scenario: Hard-deleting the last criterion referencing an ObjectTag also removes that ObjectTag
  Given a CompetencyCriterion exists, no other CompetencyCriterion references its oel_tagging_objecttag, and no StudentCompetencyCriteriaStatus row references the criterion
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the CompetencyCriterion row no longer exists
  And the oel_tagging_objecttag row it referenced no longer exists

Scenario: Archiving (not hard-deleting) a criterion never touches its tagged object
  Given a CompetencyCriterion exists and a StudentCompetencyCriteriaStatus row references it
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the oel_tagging_objecttag row it references still exists, whether or not any other criterion references it

Scenario: Hard-deleting a group's only criterion cascade-deletes the now-empty group
  Given a CompetencyCriteriaGroup has exactly one CompetencyCriterion, no StudentCompetencyCriteriaStatus row references it, and no StudentCompetencyCriteriaGroupStatus row references the group
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the CompetencyCriteriaGroup row no longer exists in the database
  And a subsequent POST to the create-criterion endpoint for that group_id returns status code 404

Scenario: Cascade-delete propagates through multiple empty ancestor groups
  Given a root CompetencyCriteriaGroup's only child is a leaf CompetencyCriteriaGroup, which has exactly one CompetencyCriterion, and no learner status of any kind references the criterion or either group
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the leaf CompetencyCriteriaGroup row no longer exists in the database
  And the root CompetencyCriteriaGroup row no longer exists in the database

Scenario: Cascade stops at an ancestor with a surviving sibling
  Given a root CompetencyCriteriaGroup has two child leaf groups, each with one CompetencyCriterion, and no learner status references either criterion
  When a DELETE request removes one leaf group's criterion
  Then the response returns status code 200
  And that leaf CompetencyCriteriaGroup row no longer exists in the database
  And the root CompetencyCriteriaGroup row still exists in the database, since its other leaf group is still active

Scenario: Archiving a group's only criterion also archives the group
  Given a CompetencyCriteriaGroup has exactly one CompetencyCriterion, and a StudentCompetencyCriteriaStatus row references it
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the response body's "archived" is true
  And the CompetencyCriteriaGroup row still exists in the database with archived=true

Scenario: An archive cascades upward through an ancestor with no other active content
  Given a root CompetencyCriteriaGroup's only child is a leaf CompetencyCriteriaGroup, which has exactly one CompetencyCriterion referenced by a StudentCompetencyCriteriaStatus row
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the leaf CompetencyCriteriaGroup row still exists in the database with archived=true
  And the root CompetencyCriteriaGroup row still exists in the database with archived=true

Scenario: A group with its own direct learner status is archived, not hard-deleted, even with zero remaining children
  Given a CompetencyCriteriaGroup has exactly one CompetencyCriterion, no StudentCompetencyCriteriaStatus row references the criterion, and a StudentCompetencyCriteriaGroupStatus row directly references the group
  When a DELETE request removes that criterion
  Then the response returns status code 200
  And the response body's "archived" is false (the criterion itself was hard-deleted)
  And the CompetencyCriteriaGroup row still exists in the database with archived=true

Scenario: Reject removal for a criterion/group mismatch
  Given a CompetencyCriterion exists under group A
  When a DELETE request is sent to the remove-criterion endpoint using group B's id and that criterion's id
  Then the response returns status code 404

Scenario: Reject removal for a criterion that does not exist
  Given the referenced criterion id does not exist
  When a DELETE request is sent referencing that id
  Then the response returns status code 404

Scenario: Reject removal without permission
  Given the requesting user lacks studio write access to the criterion's course, or lacks view access to the taxonomy owning the competency
  When a DELETE request is sent to the remove-criterion endpoint
  Then the response returns status code 403