docs: add ADR for pathway and pathway item boundaries

docs/openedx_learning/decisions/0005-pathway-and-pathway-items.rst

@@ -0,0 +1,62 @@
+.. _openedx-learning-adr-0005:
+
+5. Pathways: The Boundary Between Pathway and Pathway Item
+==========================================================
+
+Status
+------
+
+Draft
+
+Context
+-------
+
+A Pathway is a set of requirements that a learner works through to earn some larger achievement, such as a
+certificate. Each requirement is represented by a **Pathway Item**. We want to draw the boundary between these two
+concepts so that the Pathway level stays stable while the Item level - and especially the ways Items get fulfilled -
+can evolve.
+
+Decisions
+---------
+
+1. A Pathway holds an ordered list of Pathway Items. The order is author-defined and is the order in which Items are
+   presented to learners. In the future, we plan to also support enforcing the order of completion.
+
+2. A Pathway Item has its own identity and lifecycle. An Item may be fulfilled by one thing today (e.g. passing a
+   course) and by something else tomorrow (e.g. a competency attainment, or an admin override) without changing its
+   identity - and therefore without changing the Pathway that contains it. How fulfillment is modeled is a separate
+   decision (:ref:`openedx-learning-adr-0006`).
+
+3. Pathway to Item relationships do not break new ground structurally. We already have precedent for modeling
+   parent-child relations in ``openedx_content`` containers; Pathway/PathwayItem will not use Container directly,
+   as they don't need Container's full complexity.
+
+4. **Item completion and Pathway completion are separate concerns.** An Item is complete or not, determined by its own
+   fulfillment rules; the Pathway's completion is computed from Item completion.
+
+5. In the MVP, Pathway completion is not configurable: a Pathway is complete when *all* of its Items are complete.
+   Because every Item is fulfilled by passing a course (:ref:`openedx-learning-adr-0006`), this means the learner has
+   passed every course in the Pathway, with grade and passed/failed state read directly from each course. Configurable
+   criteria (e.g. "complete 4 of these 5 Items") are expected in later iterations, and the intent is for them to be
+   expressed in terms of Item completion rather than the Pathway-specific definition of what fulfills each Item.
+
+6. The Item completion contract is deliberately minimal for now - complete or not. It can be extended later to carry
+   grades or other metadata, if more complex Pathway-level criteria or learner-facing displays need it.
+
+.. Run `dot -Tsvg images/pathway-and-items.dot > images/pathway-and-items.svg` to regenerate the diagram after making
+   changes to `images/pathway-and-items.dot`.
+
+.. image:: images/pathway-and-items.svg
+   :alt: Pathway, Pathway Items, and the fulfillment boundary
+   :width: 100%
+
+Consequences
+------------
+
+- New ways of fulfilling Items can be introduced without restructuring Pathways or rewriting how Pathway completion
+  is computed.
+- Learner-facing progress ("3 of 6 Items complete") is computed from Item completion, so it also remains stable
+  across such changes.
+- Interventions like admin overrides act on Item completion and are automatically respected by Pathway completion.
+- Extending the Item completion contract beyond a yes/no is an additive change, so nothing here has to be revisited
+  to do it.

docs/openedx_learning/decisions/images/pathway-and-items.dot

@@ -0,0 +1,34 @@
+digraph pathway_and_items {
+    rankdir=LR;
+    fontname="Helvetica";
+    node [shape=box, style=rounded, fontname="Helvetica", fontsize=11];
+    edge [fontname="Helvetica", fontsize=10];
+
+    pathway [label="Pathway\nMVP completion:\nall Items complete"];
+
+    subgraph cluster_items {
+        label="Pathway Items (ordered)";
+        fontsize=10;
+        fontcolor="#4d4d4d";
+        style=dashed;
+        color="#b3b3b3";
+        item1 [label="Item 1"];
+        item2 [label="Item 2"];
+        item3 [label="Item 3"];
+        item1 -> item2 -> item3 [style=dotted, arrowsize=0.7, color="#808080", constraint=false];
+        {rank=same; item1; item2; item3;}
+    }
+
+    fulfill [label="things that fulfill Items\n(courses today;\nsections, competencies,\nadmin overrides later)", style="rounded,dashed"];
+
+    pathway -> item1 [label="reads completion"];
+    pathway -> item2;
+    pathway -> item3;
+
+    item1 -> fulfill [style=dashed];
+    item2 -> fulfill [style=dashed];
+    item3 -> fulfill [style=dashed];
+
+    boundary [label="Pathway completion is computed from Item completion;\nit does not reach into what fulfills each Item", shape=plaintext, fontsize=10, fontcolor="#4d4d4d"];
+    {rank=same; pathway; boundary;}
+}