prodc 0.4.2__tar.gz → 0.4.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.4.2
+Version: 0.4.3
 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.2 → prodc-0.4.3}/pyproject.toml

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

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

@@ -7,6 +7,7 @@ formatting: it reads the resolved model and returns strings, never loads or writ
 
 from __future__ import annotations
 
+import datetime
 import shutil
 from collections.abc import Callable
 
@@ -27,6 +28,7 @@ from ..status import (
     PrincipleReport,
     Recurrence,
     Summary,
+    group_state,
     orphaned_decisions,
     rank,
     state_priority,
@@ -209,12 +211,21 @@ def render_out_of_scope(results: list[NeedResult]) -> str:
 
 
 def render_goals(goal_cov: list[tuple[Goal, Summary]], ungoaled: list[NeedResult]) -> str:
-    """Per-goal coverage, plus the needs that serve no objective (#27)."""
+    """Per-goal coverage with a derived state and target, plus the needs that serve no objective (#27, #80)."""
+    today = datetime.date.today().isoformat()
     out = ["\ngoals (objectives needs trace up to):"]
     for goal, gsum in goal_cov:
+        state = group_state(gsum)
         metric = f"  [{goal.metric}]" if goal.metric else ""
         pct = round(gsum.coverage * 100)
-        out.append(f"  {goal.id:<12} {gsum.delivered}/{gsum.total} ({pct}%){metric}  {goal.text}")
+        overdue = goal.target is not None and goal.target < today and state is not NeedState.DELIVERED
+        target = ""
+        if goal.target:
+            target = f"  ⚠ overdue {goal.target}" if overdue else f"  target {goal.target}"
+        out.append(
+            f"  {goal.id:<12} {_LABEL[state]:<10} {gsum.delivered}/{gsum.total} ({pct}%)"
+            f"{metric}{target}  {goal.text}"
+        )
     if ungoaled:
         ids = ", ".join(r.need.id for r in ungoaled)
         out.append(f"  ⚠ {len(ungoaled)} need(s) serve no goal: {ids}")

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

@@ -13,7 +13,7 @@ from ..board import need_payload
 from ..board import warrant as _warrant
 from ..dedup import DupPair, VariantGroup
 from ..model import Decision, Goal, NeedResult, NeedState, Release, Role
-from ..status import Handoff, PrincipleReport, Recurrence, Summary, rank
+from ..status import Handoff, PrincipleReport, Recurrence, Summary, group_state, rank
 from .common import brief_open
 
 
@@ -119,6 +119,9 @@ def to_json(
                 "id": goal.id,
                 "text": goal.text,
                 "metric": goal.metric,
+                "description": goal.description,
+                "target": goal.target,
+                "state": group_state(gsum).value,
                 "coverage": round(gsum.coverage, 4),
                 "delivered": gsum.delivered,
                 "total": gsum.total,

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

@@ -322,6 +322,8 @@ def _goal(raw: object, where: str) -> Goal:
         id=_as_str(tbl.get("id"), f"{where}.id"),
         text=_as_str(tbl.get("text"), f"{where}.text"),
         metric=_opt_str(tbl.get("metric"), f"{where}.metric"),
+        description=_opt_str(tbl.get("description"), f"{where}.description"),
+        target=_opt_str(tbl.get("target"), f"{where}.target"),
     )
 
 

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

@@ -102,11 +102,20 @@ class Goal:
 
     A need with no ``goal`` is flagged the way an unsourced need is flagged an opinion — it
     lets the board answer "are we moving the objective", not only "is this need delivered".
+
+    A goal is also the home for the long-lived container other trackers call an *initiative* or
+    *epic* (#80): a ``description`` and an optional ``target`` window give it a title, a blurb and a
+    deadline, and its state is *derived* from the needs that cite it (:func:`~prodc.status.group_state`),
+    never hand-set — so an "is this big piece of work done" rolls up from the proofs, not a status
+    field that drifts. No separate ``initiative`` noun: an output bundle that is neither an outcome
+    (goal) nor a ship slice (release) is engineering tracking, not product.
     """
 
     id: str
     text: str
     metric: str | None = None  # how the objective is measured, e.g. "churn < 5%"
+    description: str | None = None  # optional longer blurb — the initiative's prose (#80)
+    target: str | None = None  # optional ISO date the objective is aimed at; past + not DELIVERED warns
 
 
 @dataclass(frozen=True)

{prodc-0.4.2 → prodc-0.4.3}/src/prodc/report.py

@@ -14,7 +14,7 @@ from datetime import date
 from .board import gather
 from .config import Config
 from .model import Model, NeedResult, NeedState
-from .status import active_decisions, principle_report, state_priority
+from .status import active_decisions, group_state, principle_report, state_priority
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -97,11 +97,12 @@ def render_markdown(
             out.append("")
 
     if model.goals:
-        out += ["## Goals", "", "| goal | delivered | goal |", "|---|---|---|"]
+        out += ["## Goals", "", "| goal | state | delivered | target | goal |", "|---|---|---|---|---|"]
         for goal, gsum in goal_cov:
             out.append(
-                f"| {goal.id} | {gsum.delivered}/{gsum.total} ({round(gsum.coverage * 100)}%) "
-                f"| {goal.text} |"
+                f"| {goal.id} | {_LABEL[group_state(gsum)]} "
+                f"| {gsum.delivered}/{gsum.total} ({round(gsum.coverage * 100)}%) "
+                f"| {goal.target or ''} | {goal.text} |"
             )
         if ungoaled:
             out.append("")

{prodc-0.4.2 → prodc-0.4.3}/src/prodc/report_html.py

@@ -15,7 +15,7 @@ from datetime import date
 from .board import gather, need_payload
 from .config import Config
 from .model import Model
-from .status import active_decisions, principle_report
+from .status import active_decisions, group_state, principle_report
 
 
 def board_payload(
@@ -55,7 +55,16 @@ def board_payload(
             for r in results
             if r.need.product and not r.need.is_withdrawn
         ],
-        "goals": [{"id": g.id, "text": g.text, **_cov(s.delivered, s.total)} for g, s in goal_cov],
+        "goals": [
+            {
+                "id": g.id,
+                "text": g.text,
+                "target": g.target,
+                "state": group_state(s).value,
+                **_cov(s.delivered, s.total),
+            }
+            for g, s in goal_cov
+        ],
         "ungoaled": [r.need.id for r in ungoaled],
         "releases": [
             {"id": rel.id, "text": rel.text, **_cov(s.delivered, s.total)} for rel, s in rel_cov

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

@@ -385,6 +385,26 @@ def summarize(results: list[NeedResult]) -> Summary:
     )
 
 
+def group_state(s: Summary) -> NeedState:
+    """The derived state of an FK group (goal, release, role) — the roll-up of its members (#80).
+
+    One function behind every group's state, so a goal/initiative, a release slice and a role all
+    read the same way and none carries a hand-set status that can drift from its needs: BROKEN if
+    any member proof is broken, UNRESOLVED if any source couldn't be read, DELIVERED only when every
+    member is, HOLE when nothing is covered yet, else PENDING (in progress). An empty group is a
+    HOLE (nothing delivered, nothing pending).
+    """
+    if s.broken:
+        return NeedState.BROKEN
+    if s.unresolved:
+        return NeedState.UNRESOLVED
+    if s.total and s.delivered == s.total:
+        return NeedState.DELIVERED
+    if s.delivered == 0 and s.pending == 0:
+        return NeedState.HOLE
+    return NeedState.PENDING
+
+
 @dataclass(frozen=True)
 class Recurrence:
     """A baseline need and the clients that carry a variant of it (#32)."""

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

@@ -262,6 +262,26 @@ def test_goals_loaded_and_need_traces_up(tmp_path: Path) -> None:
     assert model.needs[0].goal == "G-1"
 
 
+def test_goal_loads_description_and_target(tmp_path: Path) -> None:
+    # #80: a goal is the home for the initiative — a description and an optional target window.
+    from prodc.loader import load
+
+    cfg = _config(
+        tmp_path,
+        (
+            "goals.yaml",
+            "goals:\n"
+            "  - id: INIT-SEARCH\n"
+            "    text: Second-generation search\n"
+            "    description: the long blurb\n"
+            "    target: 2026-12-15\n",
+        ),
+    )
+    goal = load(cfg).goals[0]
+    assert goal.description == "the long blurb"
+    assert goal.target == "2026-12-15"
+
+
 def test_need_goal_unknown_raises(tmp_path: Path) -> None:
     cfg = _config(tmp_path, ("a.yaml", "needs:\n  - id: N-1\n    text: t\n    goal: NOPE\n"))
     with pytest.raises(LoaderError, match="goal 'NOPE' is not a known goal id"):

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

@@ -7,7 +7,23 @@ from pathlib import Path
 
 from prodc.adapters import FrontmatterAdapter, ProofResult, SourceAdapter
 from prodc.model import Child, Need, NeedState, ProofState, Source, SourceKind
-from prodc.status import resolve
+from prodc.status import Summary, group_state, resolve
+
+
+def _summary(**kw: int) -> Summary:
+    base = dict(total=0, delivered=0, pending=0, hole=0, must_hole=0, broken=0, unresolved=0, opinion=0)
+    base.update(kw)
+    return Summary(**base)
+
+
+def test_group_state_rolls_up_members() -> None:
+    # #80: a goal/release/role state is derived from its members, never hand-set.
+    assert group_state(_summary()) is NeedState.HOLE  # empty group
+    assert group_state(_summary(total=2, hole=2)) is NeedState.HOLE  # nothing started
+    assert group_state(_summary(total=2, delivered=2)) is NeedState.DELIVERED
+    assert group_state(_summary(total=2, delivered=1, pending=1)) is NeedState.PENDING
+    assert group_state(_summary(total=2, delivered=1, broken=1)) is NeedState.BROKEN  # broken wins
+    assert group_state(_summary(total=2, delivered=1, unresolved=1)) is NeedState.UNRESOLVED
 
 
 @dataclass(frozen=True)