feat: add mastery status lookup and the three learner status models

[jesperhodge]

Implements #642: the mastery status lookup table and the three learner status tables that
track a learner's progress toward demonstrating a competency, at the leaf, group and
competency levels.

Stacked on #641 (PR #800). This branch is based on #800's head, not on main. #641 turns
applets/cbe/models.py into a models/ package and owns migrations 0002 and 0003, so a
branch developed off main conflicts with it irreconcilably rather than merging. Because #800's
branch lives on a fork, GitHub cannot target it as this PR's base, so the diff below includes
#800's commits until #800 merges. Review this PR's own commit (9a3ce50) in isolation, or wait
for #800.

What lands

Four models in src/openedx_learning/applets/cbe/models/learner_status.py:

Model	Tracks	Node foreign key
CompetencyMasteryStatus	The three possible status values	(lookup table)
StudentCompetencyCriteriaStatus	Leaf level	CompetencyCriterion
StudentCompetencyCriteriaGroupStatus	Group level	CompetencyCriteriaGroup
StudentCompetencyStatus	Competency level	oel_tagging.Tag

Plus migrations 0004_learner_status_models and 0005_seed_competency_mastery_statuses, four
read-only Django admin pages, and 24 tests.

The status ordering lives in pinned primary keys

The data migration seeds AttemptedNotDemonstrated as id 1, PartiallyAttempted as 2 and
Demonstrated as 3, and a MasteryStatus enum names them. #642 leaves the mechanism open
between that and a rank column. Pinned ids, for three reasons:

1. The check constraint forces pinned ids regardless. The constraint restricting
   StudentCompetencyStatus has to be a single-row CHECK, because MySQL allows no subquery
   inside one, so it can only compare the row's own status_id against a literal. I verified the
   compiled SQL: Q(status__in=(2, 3)) becomes CHECK ("status_id" IN (2, 3)), no join. With the
   ids already load-bearing constants, a rank column would be a second source of truth for the
   same ordering, and two orderings can drift.
2. The acceptance criteria cap the columns at ADR-0002 Decision 6's two for this table, id
   and status.
3. The conditional update stays single-table. Raising a status is
   filter(user=…, criterion=…, status_id__lt=new_id).update(…), which I verified compiles to one
   UPDATE … WHERE … < with no subquery. A rank column would need a join.

Cost, stated plainly: a fourth status can be added above or below the existing three but not
between them. If that is ever needed, a rank column can be added then and backfilled from id.
Precedent for pinning a primary key for system-owned lookup data already exists here, in
src/openedx_tagging/migrations/0012_language_taxonomy.py.

The enum subclasses IntegerChoices rather than enum.IntEnum for a verified reason: Django's
migration serializer writes an IntegerChoices member as a bare integer, whereas an IntEnum
member serializes as an import of the defining module. That keeps the migrations independent of
later edits to the enum.

Deletion behaviour

Every value here is final. #655 closed with an approved design, and #799 is closed as superseded.

Foreign key	Value
user	CASCADE
node (criterion / group / tag)	PROTECT
status	PROTECT

The node PROTECT values are load-bearing, not defensive. #641's four
definition-to-definition foreign keys are CASCADE, so deleting a Tag makes Django's collector
walk down into its criteria groups and then their criteria. These PROTECT values are the only
thing that stops that walk, and they are what turns ADR-0002 Decision 7's guarantee into
behaviour: the delete succeeds when no learner holds status beneath the row, and raises
ProtectedError when one does. PROTECT is evaluated on every row the collector reaches, not
only the row passed to delete(), which is why the transitive cases work. #675 re-implements the
same predicate at the API layer for a clean status code; this is the backstop for paths that never
reach it.

They are deliberately stricter than that predicate. ADR-0002 Decision 7, as amended for #655,
names only the leaf table StudentCompetencyCriteriaStatus as determining whether a record is
protected, treating the two roll-up tables as derived and not independently checked. The database
makes no such distinction, so a roll-up row with no leaf beneath it would also block a delete.
That should not occur, and failing closed is the right default for a backstop.

user is CASCADE, not PROTECT, because PROTECT would let this library veto
User.delete() platform-wide from openedx-platform code that has no reason to know CBE rows
exist. SET_NULL was never a candidate: a null user_id breaks the (user_id, node_id)
uniqueness the in-place-update design rests on. CASCADE rather than DO_NOTHING, which an
earlier revision of #642 offered, because DO_NOTHING does not do what its name suggests: Django
implements on_delete in Python, and MySQL builds all of these foreign keys as ON DELETE NO ACTION whatever is declared, so DO_NOTHING leaves the constraint in force and raises
IntegrityError instead of orphaning. A real orphan needs db_constraint=False, which drops
referential integrity on user_id entirely. Both behaviours were verified against a database.

Tests

24 tests. Every ProtectedError case #613 describes is here rather than in #641, because
asserting one needs a Student*Status row and this is the change that creates those tables. Each
case covers both halves, and the blocking status is spread across the three tables so all three
PROTECT values are shown firing:

Deleting	Blocked by	Succeeds when
oel_tagging_tag	a competency status on the tag	no status beneath: whole criteria tree cascades away
CompetencyCriteriaGroup at depth	a leaf status two hops down	no status beneath
oel_tagging_objecttag	a leaf status on its criterion	no status: that criterion cascades away
oel_tagging_taxonomy	a group status under one of its tags	—

Plus: a user delete removing that user's rows across all three models; the single-statement
monotone comparison on the leaf, where ADR-0004 Decision 1 puts automatic writes; the check
constraint on create(), bulk_create() and QuerySet.update(), none of which call clean();
the two roll-up models accepting all three status values, which is the constraint's boundary; one
row per learner and node on each model; and no history attribute on any of them.

Verification

Green on SQLite and MySQL 8: 74 tests (24 here, 50 from #800), pylint, pycodestyle,
pydocstyle, isort, mypy, lint-imports, and makemigrations openedx_learning --check.
showmigrations confirms a single leaf, and the chain applies from an empty database with the
three lookup rows seeded.

All ten ADR-0002 Decision 5 indexes verified present, by introspecting a migrated MySQL
database rather than by reading the models. The five that must be unique are unique: 6, 7, 8, 9
and 10. Django's SQLite introspection cannot do this check, as it fails on
CompetencyRuleProfile's GeneratedField.

Two deliberate divergences from the acceptance criteria

Timestamps use manual_date_time_field(), not auto_now_add/auto_now. auto_now is
applied by DateTimeField.pre_save, which only runs on Model.save(); I verified that
QuerySet.update() carries only the values passed to it. So under auto_now, modified would go
stale on exactly the conditional-UPDATE path ADR-0004 Decision 4 mandates. This also matches the
repo's own rule: manual_date_time_field() is used in the publishing and versioning core, where
one logical operation writes many rows that should share a timestamp, and a rollup writing a leaf
and its ancestors across several commits is squarely that case. The field names, created and
modified, are unchanged and match OEP-38.

The model class is CompetencyMasteryStatus, singular, where #642 and ADR-0002 write
CompetencyMasteryStatuses. Django models are singular by convention, and #641 applies the same
resolution in naming its class CompetencyCriterion.

A third divergence from earlier revisions of this PR is now resolved: the foreign key columns
carry explicit db_column values matching ADR-0002 Decision 6 exactly, following #641's approach
of pairing an idiomatic Python attribute with the ADR's column name.

Known gaps

pii_check does not pass, for reasons that predate this feature. Every model #613 adds is
annotated, including #641's three Historical* models: none of the 20 models the coverage report
lists as uncovered belongs to openedx_learning. But the repo sits at 71.8% coverage with two
lint errors (openedx_content.Draft and openedx_content.PublishableEntityVersion are both
annotated and safelisted), and I confirmed both are identical on #800's head with none of this
work applied. #642's whole-feature gate asks for make pii_check at 100%, which cannot be reached
without annotating 20 models across oel_*, openedx_catalog, openedx_content, organizations
and test_django_app. That is out of scope here and needs its own issue.

openedx-platform companion work is unfiled. That repo lists every openedx-core model
individually in its own safe list, so the first pin bump including #641 and this change drops its
pii_check below target until ten entries are added. #642's Out of scope section records this;
filing it is not this PR's work.

🤖 Generated with Claude Code

[openedx-webhooks]

Thanks for the pull request, @jesperhodge!

This repository is currently maintained by @axim-engineering.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

• If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
  • This process (including the steps you'll need to take) is documented here.
• If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

• Dependencies

  This PR must be merged before / after / at the same time as ...

• Blockers

  This PR is waiting for OEP-1234 to be accepted.

• Timeline information

  This PR must be merged by XX date because ...

• Partner information

  This is for a course on edx.org.

• Supporting documentation
• Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.

---

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

• The size and impact of the changes that it introduces
• The need for product review
• Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.