prodc 0.4.2__tar.gz → 0.4.4__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.4.2"
+version = "0.4.4"
 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.4}/src/prodc/cli/app.py

@@ -181,6 +181,13 @@ def main(argv: list[str] | None = None) -> int:
         help="principle only: promote a need into a principle — copy its text (unless --text "
         "overrides) and its sources as the provenance that surfaced it; the need stays on the board",
     )
+    ad.add_argument(
+        "--scope",
+        default="product",
+        metavar="SCOPE",
+        help="principle only: its scope — product (default), design, visual, engineering; "
+        "must be declared in [principles].scopes",
+    )
     ad.add_argument(
         "--needs",
         default=None,

{prodc-0.4.2 → prodc-0.4.4}/src/prodc/cli/commands.py

@@ -557,6 +557,7 @@ def cmd_add(args: argparse.Namespace) -> int:
                 text,
                 file=args.file,
                 revised_at=date.today().isoformat(),
+                scope=args.scope,
                 sources=sources,
                 expect_sha=args.expect_sha,
                 dry_run=args.dry_run,

{prodc-0.4.2 → prodc-0.4.4}/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}")
@@ -274,11 +285,12 @@ def render_principles(reports: list[PrincipleReport]) -> str:
     An principle is held as given, not validated; ``declined`` are the needs withdrawn citing it, and
     ``stale`` (the ripple) are those decided before its latest ``revised_at`` — flagged to re-review.
     """
-    out = ["\nprinciples (the product vision — held as given):"]
+    out = ["\nprinciples (the vision — held as given):"]
     for rep in reports:
         a = rep.principle
         rev = f"revised {a.revised_at}" if a.revised_at else "undated"
-        out.append(f"  {a.id:<6} {rev}  {a.text}")
+        scope = "" if a.scope == "product" else f"[{a.scope}] "
+        out.append(f"  {a.id:<6} {scope}{rev}  {a.text}")
         if rep.declined:
             out.append(f"        declined: {', '.join(n.id for n in rep.declined)}")
         if rep.stale:

{prodc-0.4.2 → prodc-0.4.4}/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.4}/src/prodc/config.py

@@ -119,6 +119,7 @@ class Config:
     default_draft: bool = False  # [add].default_draft — `add` stages as draft by default (#60)
     callbacks: tuple[Callback, ...] = ()  # [[callbacks.hooks]] — lifecycle callbacks (#71)
     callback_state_file: str = ".prodc/state.json"  # [callbacks].state_file — the state ledger
+    principle_scopes: tuple[str, ...] = ("product",)  # [principles].scopes — allowed scopes (#88)
 
     def importance_label(self, level: int | None) -> str | None:
         """The declared label for an importance level, or None if unset/undeclared (#59)."""
@@ -302,6 +303,15 @@ class Config:
 
         callbacks, callback_state_file = _callbacks(raw)
 
+        principles_tbl = _as_dict(raw.get("principles", {}), "[principles]")
+        if "scopes" in principles_tbl:
+            scopes = _as_str_list(principles_tbl["scopes"], "[principles].scopes")
+            if not scopes:
+                raise ConfigError("[principles].scopes must list at least one scope")
+            principle_scopes = tuple(scopes)
+        else:
+            principle_scopes = ("product",)
+
         return cls(
             root=root,
             need_globs=need_globs,
@@ -315,4 +325,5 @@ class Config:
             default_draft=default_draft,
             callbacks=callbacks,
             callback_state_file=callback_state_file,
+            principle_scopes=principle_scopes,
         )

{prodc-0.4.2 → prodc-0.4.4}/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"),
     )
 
 
@@ -347,6 +349,7 @@ def _principle(raw: object, where: str) -> Principle:
     return Principle(
         id=_as_str(tbl.get("id"), f"{where}.id"),
         text=_as_str(tbl.get("text"), f"{where}.text"),
+        scope=_opt_str(tbl.get("scope"), f"{where}.scope") or "product",
         revised_at=_opt_str(tbl.get("revised_at"), f"{where}.revised_at"),
         sources=tuple(
             _source(s, f"{where}.sources[{i}]")
@@ -532,6 +535,7 @@ def load(config: Config) -> Model:
     _check_withdrawal_of(acc.needs)
     _check_source_roles(acc.needs, acc.principles, {p.id for p in acc.roles})
     _check_decisions(acc.decisions, {n.id for n in acc.needs}, {p.id for p in acc.principles})
+    _check_principle_scopes(acc.principles, config.principle_scopes)
     acc.needs = _symmetrize_contradicts(acc.needs)
     return Model(
         needs=tuple(acc.needs),
@@ -585,6 +589,17 @@ def _check_children(needs: list[Need]) -> None:
                 raise LoaderError(f"need {need.id!r}: child {c.id!r} is not a known need id")
 
 
+def _check_principle_scopes(principles: list[Principle], allowed: tuple[str, ...]) -> None:
+    """Every principle's ``scope`` must be one declared in ``[principles].scopes`` (#88)."""
+    allowed_set = set(allowed)
+    for p in principles:
+        if p.scope not in allowed_set:
+            raise LoaderError(
+                f"principle {p.id!r}: scope {p.scope!r} is not declared in "
+                f"[principles].scopes ({', '.join(allowed)})"
+            )
+
+
 def _check_withdrawal_of(needs: list[Need]) -> None:
     """A withdrawal's ``of`` must name a known need (never itself); required when kind is duplicate.
 

{prodc-0.4.2 → prodc-0.4.4}/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)
@@ -153,11 +162,18 @@ class Principle:
     client), and ``revised_at`` dates its latest statement. A decision taken under an older version
     of the principle is flagged for re-review when the principle is revised — the ripple. A separate noun
     (like :class:`Role`), not a Need marker: a principle is a stance, not what a person wants, so it
-    never enters coverage, the plan, or the opinion check.
+    never enters coverage, the plan, or the opinion check — in every ``scope`` (#88).
+
+    ``scope`` says which kind of commitment it is — product, design, visual, engineering — so design,
+    visual and engineering principles live on the board beside product ones instead of in prose docs
+    and code comments, where a Decision or an ``out_of_scope`` withdrawal cannot cite them. The scope
+    must be one declared in ``[principles].scopes`` (default ``["product"]``); an undeclared scope is a
+    load error the author owns.
     """
 
     id: str
     text: str
+    scope: str = "product"  # product/design/visual/engineering — declared in [principles].scopes (#88)
     revised_at: str | None = None  # ISO date the principle was last stated or revised
     sources: tuple[Source, ...] = ()  # the signals that surfaced it — provenance, not validation
 

{prodc-0.4.2 → prodc-0.4.4}/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("")
@@ -153,18 +154,18 @@ def render_markdown(
 
     if model.principles:
         out += [
-            "## Principles (the product vision — held as given)",
+            "## Principles (the vision — held as given)",
             "",
-            "| principle | stated | needs declined under it |",
-            "|---|---|---|",
+            "| principle | scope | stated | needs declined under it |",
+            "|---|---|---|---|",
         ]
         for rep in principle_report(list(model.needs), list(model.principles)):
             text = rep.principle.text.replace("|", "\\|")
             declined = ", ".join(n.id for n in rep.declined) or "—"
             stale = f" _(re-review {', '.join(n.id for n in rep.stale)})_" if rep.stale else ""
             out.append(
-                f"| {rep.principle.id}: {text} | {rep.principle.revised_at or '—'} "
-                f"| {declined}{stale} |"
+                f"| {rep.principle.id}: {text} | {rep.principle.scope} "
+                f"| {rep.principle.revised_at or '—'} | {declined}{stale} |"
             )
         out.append("")
 

{prodc-0.4.2 → prodc-0.4.4}/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.4}/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.4}/src/prodc/writer.py

@@ -914,6 +914,7 @@ def add_principle(
     *,
     file: str,
     revised_at: str,
+    scope: str = "product",
     sources: tuple[Source, ...] = (),
     expect_sha: str | None = None,
     dry_run: bool,
@@ -943,7 +944,10 @@ def add_principle(
         for a in principles
     ):
         raise WriteError(f"principle {principle_id!r} already exists in {target.name}")
-    entry: dict[str, object] = {"id": principle_id, "text": text, "revised_at": revised_at}
+    entry: dict[str, object] = {"id": principle_id, "text": text}
+    if scope != "product":
+        entry["scope"] = scope  # written only when non-default, to keep the common case clean
+    entry["revised_at"] = revised_at
     if sources:
         entry["sources"] = [_source_dict(s) for s in sources]
     principles.append(entry)

{prodc-0.4.2 → prodc-0.4.4}/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.4}/tests/test_principles.py

@@ -132,6 +132,53 @@ principles:
         load(Config.load(_project(tmp_path, needs=needs)))
 
 
+# --- scope (#88) ------------------------------------------------------------
+
+_SCOPED_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+
+[principles]
+scopes = ["product", "visual", "engineering"]
+"""
+
+
+def test_principle_scope_defaults_to_product(tmp_path: Path) -> None:
+    needs = "principles:\n  - id: P-1\n    text: a principle\n"
+    model = load(Config.load(_project(tmp_path, needs=needs)))
+    assert model.principles[0].scope == "product"
+
+
+def test_declared_scope_loads(tmp_path: Path) -> None:
+    needs = "principles:\n  - id: P-1\n    text: colour is load-bearing\n    scope: visual\n"
+    model = load(Config.load(_project(tmp_path, toml=_SCOPED_TOML, needs=needs)))
+    assert model.principles[0].scope == "visual"
+
+
+def test_undeclared_scope_rejected(tmp_path: Path) -> None:
+    # default [principles].scopes is just ["product"], so "visual" is undeclared here.
+    needs = "principles:\n  - id: P-1\n    text: a principle\n    scope: visual\n"
+    with pytest.raises(LoaderError, match="scope 'visual' is not declared"):
+        load(Config.load(_project(tmp_path, needs=needs)))
+
+
+def test_add_principle_writes_scope(tmp_path: Path) -> None:
+    from prodc.writer import add_principle
+
+    cfg = Config.load(_project(tmp_path, toml=_SCOPED_TOML, needs="principles:\n  - id: P-0\n    text: seed\n"))
+    add_principle(
+        cfg,
+        "P-9",
+        "colour is load-bearing",
+        file="needs/a.yaml",
+        revised_at=date.today().isoformat(),
+        scope="visual",
+        dry_run=False,
+    )
+    model = load(cfg)
+    assert next(p for p in model.principles if p.id == "P-9").scope == "visual"
+
+
 # --- principle_report (declined / stale) ------------------------------------
 
 
@@ -275,7 +322,7 @@ def test_status_text_shows_principles_section(
 
     main(["status", "--config", str(_project(tmp_path))])
     out = capsys.readouterr().out
-    assert "principles (the product vision — held as given):" in out
+    assert "principles (the vision — held as given):" in out
     assert "P-1" in out and "revised 2026-10-15" in out
     assert "declined: N-7, N-9" in out
     assert "decided before the latest revision: N-7 — re-review" in out

{prodc-0.4.2 → prodc-0.4.4}/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)