prodc 0.4.1__tar.gz → 0.4.2__tar.gz

{prodc-0.4.1 → prodc-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.4.1
+Version: 0.4.2
 Summary: Product management as code: roles, flows, and features traced to evidence.
 Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
 Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc

{prodc-0.4.1 → prodc-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.4.1"
+version = "0.4.2"
 description = "Product management as code: roles, flows, and features traced to evidence."
 readme = "README.md"
 requires-python = ">=3.12"

{prodc-0.4.1 → prodc-0.4.2}/src/prodc/cli/render.py

@@ -382,7 +382,10 @@ def render_show(
     else:
         lines.append("  sources: (none — opinion)")
     if need.children:
-        lines.append(f"  children: {', '.join(need.children)}")
+        rendered = ", ".join(
+            c.id if c.step is None else f"{c.id}@{c.step}" for c in need.children
+        )
+        lines.append(f"  children: {rendered}")
     if need.contradicts:
         lines.append(f"  contradicts: {', '.join(need.contradicts)}")
     if need.seam:

{prodc-0.4.1 → prodc-0.4.2}/src/prodc/cli/serialize.py

@@ -160,7 +160,7 @@ def show_json(r: NeedResult, decisions: list[Decision] | None = None) -> str:
                 for s in need.sources
             ],
             "proofs": list(need.proofs),
-            "children": list(need.children),
+            "children": [{"id": c.id, "step": c.step} for c in need.children],
             "seam": list(need.seam),
         }
     )

{prodc-0.4.1 → prodc-0.4.2}/src/prodc/loader.py

@@ -21,6 +21,7 @@ from .model import (
     Answer,
     Attestation,
     AttestationKind,
+    Child,
     Decision,
     Goal,
     Model,
@@ -203,6 +204,21 @@ def _source(raw: object, where: str) -> Source:
     )
 
 
+def _child(raw: object, where: str) -> Child:
+    """Parse one flow edge: a bare id string, or a ``{id, step}`` mapping (#90).
+
+    A bare ``US-050`` stays valid (``Child("US-050")`` with no step), so existing flows load
+    unchanged; a mapping adds the optional ``step`` the edge plays in the journey.
+    """
+    if isinstance(raw, str):
+        return Child(id=raw)
+    tbl = _as_mapping(raw, where)
+    return Child(
+        id=_as_str(tbl.get("id"), f"{where}.id"),
+        step=_opt_str(tbl.get("step"), f"{where}.step"),
+    )
+
+
 def _need(
     raw: object,
     where: str,
@@ -243,7 +259,7 @@ def _need(
         for i, p in enumerate(_as_list(tbl.get("proofs"), f"{where}.proofs"))
     )
     children = tuple(
-        _as_str(c, f"{where}.children[{i}]")
+        _child(c, f"{where}.children[{i}]")
         for i, c in enumerate(_as_list(tbl.get("children"), f"{where}.children"))
     )
     seam = tuple(
@@ -564,9 +580,9 @@ def _check_children(needs: list[Need]) -> None:
     """Every id in a need's ``children`` must name a known need."""
     known = {n.id for n in needs}
     for need in needs:
-        for cid in need.children:
-            if cid not in known:
-                raise LoaderError(f"need {need.id!r}: child {cid!r} is not a known need id")
+        for c in need.children:
+            if c.id not in known:
+                raise LoaderError(f"need {need.id!r}: child {c.id!r} is not a known need id")
 
 
 def _check_withdrawal_of(needs: list[Need]) -> None:

{prodc-0.4.1 → prodc-0.4.2}/src/prodc/model.py

@@ -257,6 +257,21 @@ class Withdrawal:
     of: str | None = None  # id of the need this one duplicates (required when kind is duplicate)
 
 
+@dataclass(frozen=True)
+class Child:
+    """One edge of a flow: the sub-need and, optionally, the ``step`` it plays in the journey (#90).
+
+    A flow's ``children`` are ordered, and a use case ("job") is just a flow with a ``role`` set and
+    a ``step`` on each edge (locate / execute / conclude). The step annotates the *edge*, not the
+    sub-need — the same need can be the ``execute`` step of one flow and the ``locate`` of another —
+    so it lives here, not on :class:`Need`. A bare ``US-050`` in YAML loads as ``Child("US-050")``
+    with no step, so every existing flow keeps working unchanged.
+    """
+
+    id: str
+    step: str | None = None
+
+
 @dataclass(frozen=True)
 class Need:
     """What a named person wants, with its provenance and its proofs."""
@@ -269,7 +284,7 @@ class Need:
     must: bool = False
     sources: tuple[Source, ...] = ()
     proofs: tuple[str, ...] = ()  # locators, "<adapter>:<payload>" (leaf needs)
-    children: tuple[str, ...] = ()  # ids of sub-needs (a flow is a Need with children)
+    children: tuple[Child, ...] = ()  # ordered sub-need edges (a flow is a Need with children)
     seam: tuple[str, ...] = ()  # end-to-end proof locators for a flow's between-steps behaviour
     client: str | None = None  # which client this instance is for; None = shared baseline
     variant_of: str | None = None  # id of the baseline need this specialises; None = standalone

{prodc-0.4.1 → prodc-0.4.2}/src/prodc/status.py

@@ -293,11 +293,11 @@ class Resolver:
         warnings: list[str] = []
         child_states: list[NeedState] = []
         declared = False
-        for cid in need.children:
-            if cid not in self._by_id:
-                warnings.append(f"unknown child id '{cid}'")
+        for c in need.children:
+            if c.id not in self._by_id:
+                warnings.append(f"unknown child id '{c.id}'")
                 continue
-            cr = self.resolve(cid)
+            cr = self.resolve(c.id)
             child_states.append(cr.state)
             declared = declared or cr.declared
         delivered = sum(1 for s in child_states if s is NeedState.DELIVERED)
@@ -806,7 +806,7 @@ def handoffs(needs: list[Need]) -> list[Handoff]:
     for flow in needs:
         if not flow.children:
             continue
-        steps = [by_id[c] for c in flow.children if c in by_id]
+        steps = [by_id[c.id] for c in flow.children if c.id in by_id]
         for a, b in pairwise(steps):
             if a.role and b.role and a.role != b.role:
                 out.append(Handoff(flow, a, b, a.role, b.role))
@@ -844,7 +844,7 @@ def flow_orphan_warnings(needs: list[Need]) -> set[str]:
         return set()
     in_a_flow: set[str] = set()
     for flow in flows:
-        in_a_flow.update(flow.children)
+        in_a_flow.update(c.id for c in flow.children)
     return {n.id for n in needs if not n.children and n.id not in in_a_flow}
 
 

{prodc-0.4.1 → prodc-0.4.2}/src/prodc/writer.py

@@ -365,6 +365,19 @@ def _coerce(value: str) -> object:
         return value
 
 
+def _child_item(raw: str) -> object:
+    """Parse a ``children+=`` value into a flow edge: ``id`` stays a bare string, ``id@step`` a map.
+
+    Mirrors the loader's dual shape (#90): ``children+=US-050`` appends the bare id (unstepped),
+    ``children+=US-052@execute`` appends ``{id: US-052, step: execute}``. A bare id keeps the file's
+    existing plain-string style; the ``@`` suffix mirrors the ``need:A@yes`` proof-locator idiom.
+    """
+    head, sep, step = raw.partition("@")
+    if not sep:
+        return raw
+    return {"id": head.strip(), "step": step.strip()}
+
+
 def _apply_assignment(need: dict[str, object], assignment: str, path: Path) -> None:
     if "+=" in assignment:
         key, _, raw = assignment.partition("+=")
@@ -377,7 +390,7 @@ def _apply_assignment(need: dict[str, object], assignment: str, path: Path) -> N
         if not isinstance(current, list):
             raise WriteError(f"{path.name}: {key!r} is not a list")
         items = cast("list[object]", current)
-        items.append(raw.strip())
+        items.append(_child_item(raw.strip()) if key == "children" else raw.strip())
         need[key] = items
         return
     key, sep, raw = assignment.partition("=")

{prodc-0.4.1 → prodc-0.4.2}/tests/test_loader.py

@@ -109,6 +109,26 @@ def test_flow_with_proofs_raises(tmp_path: Path) -> None:
         load_needs(cfg)
 
 
+def test_children_load_as_bare_id_or_stepped_mapping(tmp_path: Path) -> None:
+    # #90: a flow's children take either a bare id (unstepped) or a {id, step} mapping, mixed.
+    cfg = _config(
+        tmp_path,
+        (
+            "a.yaml",
+            "needs:\n"
+            "  - id: F-1\n"
+            "    text: a flow\n"
+            "    children:\n"
+            "      - C-1\n"
+            "      - {id: C-2, step: execute}\n"
+            "  - id: C-1\n    text: one\n"
+            "  - id: C-2\n    text: two\n",
+        ),
+    )
+    flow = next(n for n in load_needs(cfg) if n.id == "F-1")
+    assert [(c.id, c.step) for c in flow.children] == [("C-1", None), ("C-2", "execute")]
+
+
 def test_variant_scope_shared_baseline_across_clients(tmp_path: Path) -> None:
     cfg = _config(
         tmp_path,

{prodc-0.4.1 → prodc-0.4.2}/tests/test_models.py

@@ -14,7 +14,7 @@ from dataclasses import dataclass, replace
 from musil import Action, Model, check, explore, reaches
 
 from prodc.adapters import Adapter, ProofResult
-from prodc.model import Decision, Need, NeedState, ProofState, Withdrawal, board_needs
+from prodc.model import Child, Decision, Need, NeedState, ProofState, Withdrawal, board_needs
 from prodc.status import Resolver, active_decisions
 
 
@@ -141,7 +141,7 @@ def flow_state(f: Flow) -> NeedState:
     """The NeedState prodc's real aggregate gives this set of children + seam."""
     children = [_child_need(f"c{i}", s) for i, s in enumerate(f.children)]
     seam = tuple(f"stub:{s}" for s in f.seam if s != "none")
-    flow = Need(id="flow", text="f", children=tuple(c.id for c in children), seam=seam)
+    flow = Need(id="flow", text="f", children=tuple(Child(c.id) for c in children), seam=seam)
     return Resolver([flow, *children], _ADAPTERS).resolve("flow").state
 
 

{prodc-0.4.1 → prodc-0.4.2}/tests/test_status.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from prodc.adapters import FrontmatterAdapter, ProofResult, SourceAdapter
-from prodc.model import Need, NeedState, ProofState, Source, SourceKind
+from prodc.model import Child, Need, NeedState, ProofState, Source, SourceKind
 from prodc.status import resolve
 
 
@@ -52,7 +52,7 @@ def test_flow_aggregates_two_of_three() -> None:
         Need(id="C-2", text="two", proofs=("web:2",)),
         Need(id="C-3", text="three", proofs=()),  # a HOLE
     )
-    flow = Need(id="F-1", text="a flow", children=("C-1", "C-2", "C-3"))
+    flow = Need(id="F-1", text="a flow", children=(Child("C-1"), Child("C-2"), Child("C-3")))
     results = {r.need.id: r for r in resolve([flow, *children], {"web": _delivered()})}
     flow_result = results["F-1"]
     assert flow_result.state is NeedState.PENDING  # not all delivered → pending
@@ -234,7 +234,7 @@ def test_coverage_counts_leaves_not_flow_parents() -> None:
     from prodc.status import summarize
 
     needs = [
-        Need(id="F-1", text="roast day flow", children=("L-1", "L-2")),
+        Need(id="F-1", text="roast day flow", children=(Child("L-1"), Child("L-2"))),
         Need(id="L-1", text="step one", proofs=("x:1",)),
         Need(id="L-2", text="step two", proofs=("x:1",)),
     ]
@@ -296,7 +296,7 @@ def test_flow_orphan_warning() -> None:
     from prodc.status import flow_orphan_warnings
 
     needs = [
-        Need(id="F-1", text="a flow", children=("L-1",)),
+        Need(id="F-1", text="a flow", children=(Child("L-1"),)),
         Need(id="L-1", text="in the flow"),
         Need(id="L-2", text="in no flow"),
     ]
@@ -354,7 +354,7 @@ def test_flow_seam_proof_gates_delivered() -> None:
     # all children delivered but the seam proof pending → flow is PENDING, not DELIVERED (#44)
     from prodc.adapters import Adapter
 
-    flow = Need(id="F-1", text="roast day", children=("L-1", "L-2"), seam=("web:seam#E2E",))
+    flow = Need(id="F-1", text="roast day", children=(Child("L-1"), Child("L-2")), seam=("web:seam#E2E",))
     children = [
         Need(id="L-1", text="a", proofs=("x:1",)),
         Need(id="L-2", text="b", proofs=("x:1",)),
@@ -368,14 +368,14 @@ def test_flow_seam_proof_gates_delivered() -> None:
 
 
 def test_flow_seam_green_delivers() -> None:
-    flow = Need(id="F-1", text="roast day", children=("L-1",), seam=("web:seam#E2E",))
+    flow = Need(id="F-1", text="roast day", children=(Child("L-1"),), seam=("web:seam#E2E",))
     child = Need(id="L-1", text="a", proofs=("x:1",))
     by_id = {r.need.id: r for r in resolve([flow, child], {"x": _delivered(), "web": _delivered()})}
     assert by_id["F-1"].state is NeedState.DELIVERED
 
 
 def test_flow_seam_broken_breaks_flow() -> None:
-    flow = Need(id="F-1", text="roast day", children=("L-1",), seam=("nope:x",))
+    flow = Need(id="F-1", text="roast day", children=(Child("L-1"),), seam=("nope:x",))
     child = Need(id="L-1", text="a", proofs=("x:1",))
     by_id = {r.need.id: r for r in resolve([flow, child], {"x": _delivered()})}
     assert by_id["F-1"].state is NeedState.BROKEN  # no 'nope' adapter → seam BROKEN

{prodc-0.4.1 → prodc-0.4.2}/tests/test_writer.py

@@ -275,6 +275,33 @@ def test_delete_need_removes_the_block_keeping_others(tmp_path: Path) -> None:
     assert "# keep me" in text  # header comment survives the splice
 
 
+def test_children_append_stepped_edge(tmp_path: Path) -> None:
+    # #90: `children+=id@step` appends a {id, step} edge; a bare id stays a plain string.
+    body = (
+        "needs:\n"
+        "  - id: F-1\n    text: a flow\n    children: [N-2]\n"
+        "  - id: N-2\n    text: step two\n    proofs: ['x:1']\n"
+        "  - id: N-3\n    text: step three\n    proofs: ['x:2']\n"
+    )
+    cfg = _proj(tmp_path, body)
+    set_field(cfg, "F-1", "children+=N-3@conclude", expect_sha=None, dry_run=False)
+    flow = next(n for n in load(cfg).needs if n.id == "F-1")
+    assert [(c.id, c.step) for c in flow.children] == [("N-2", None), ("N-3", "conclude")]
+
+
+def test_children_append_bare_id(tmp_path: Path) -> None:
+    body = (
+        "needs:\n"
+        "  - id: F-1\n    text: a flow\n    children: [N-2]\n"
+        "  - id: N-2\n    text: step two\n    proofs: ['x:1']\n"
+        "  - id: N-3\n    text: step three\n    proofs: ['x:2']\n"
+    )
+    cfg = _proj(tmp_path, body)
+    set_field(cfg, "F-1", "children+=N-3", expect_sha=None, dry_run=False)
+    flow = next(n for n in load(cfg).needs if n.id == "F-1")
+    assert [(c.id, c.step) for c in flow.children] == [("N-2", None), ("N-3", None)]
+
+
 def test_delete_need_unknown_id_rejected(tmp_path: Path) -> None:
     cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: t\n")
     with pytest.raises(WriteError, match="no need 'N-9'"):