prodc 0.4.4__tar.gz → 0.4.5__tar.gz

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

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

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

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/board.py

@@ -248,5 +248,5 @@ def gather(
         handoffs=handoffs(use_needs),
         recurrence=recurrence(use_needs),
         orphans=orphans(use_needs, cfg.adapters),
-        principles=principle_report(list(model.needs), list(model.principles)),
+        principles=principle_report(list(model.needs), list(model.principles), cfg.adapters),
     )

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/cli/app.py

@@ -188,6 +188,22 @@ def main(argv: list[str] | None = None) -> int:
         help="principle only: its scope — product (default), design, visual, engineering; "
         "must be declared in [principles].scopes",
     )
+    ad.add_argument(
+        "--implemented-in",
+        default=None,
+        metavar="LOCATOR",
+        dest="implemented_in",
+        help="principle only: a locator to the one place its values live (a pointer, not a copy)",
+    )
+    ad.add_argument(
+        "--proof",
+        action="append",
+        default=None,
+        dest="principle_proofs",
+        metavar="LOCATOR",
+        help="principle only: a guard-test locator proving the code obeys it (repeatable); "
+        "never a need: reference",
+    )
     ad.add_argument(
         "--needs",
         default=None,

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

@@ -28,7 +28,7 @@ from ..dedup import (
     who_variants,
 )
 from ..loader import LoaderError, load
-from ..model import Need, NeedResult, NeedState, board_needs
+from ..model import Need, NeedResult, NeedState, PrincipleState, board_needs
 from ..report import render_markdown
 from ..report_html import render_html
 from ..status import (
@@ -229,14 +229,31 @@ def cmd_lint(args: argparse.Namespace) -> int:
     _annotate_draft_age_warnings(results, cfg)
     # The principle ripple: a need withdrawn citing a principle that was revised *after* the decision
     # comes back up — the frame it was judged against has changed since. A warning, never a hard
-    # error; prodc flags, the PM re-decides.
-    for rep in principle_report(needs, list(model.principles)):
+    # error; prodc flags, the PM re-decides. The same loop grades each principle's guards (#89): a
+    # BROKEN guard/implemented_in is a hard error (a dangling locator), a VIOLATED guard warns (the
+    # code contradicts a stated principle — surfaced, but the PM owns the reconcile).
+    principle_errors: list[str] = []
+    principle_warnings: list[tuple[str, str]] = []
+    for rep in principle_report(needs, list(model.principles), cfg.adapters):
         for n in rep.stale:
             if n.id in by_id and n.withdrawn is not None:
                 by_id[n.id].warnings.append(
                     f"withdrawn per principle {rep.principle.id} on {n.withdrawn.date}, but "
                     f"{rep.principle.id} was revised {rep.principle.revised_at} — re-review the decision"
                 )
+        if rep.state is PrincipleState.BROKEN:
+            principle_errors.append(
+                f"{rep.principle.id}: BROKEN principle guard — a proof or implemented_in locator "
+                "resolves to nothing"
+            )
+        elif rep.state is PrincipleState.VIOLATED:
+            principle_warnings.append(
+                (
+                    rep.principle.id,
+                    "VIOLATED — a guard failed: the code contradicts this principle; reconcile the "
+                    "code or revise the principle",
+                )
+            )
     # Unresolved contradiction: two needs oppose each other yet BOTH are still live — the product
     # vision has not decided between them. A warning on both sides (withdraw one out_of_scope citing
     # the principle that decides, or reconcile them).
@@ -249,10 +266,10 @@ def cmd_lint(args: argparse.Namespace) -> int:
                     f"unresolved contradiction with {far.id} — both live, the vision has not "
                     "decided yet (withdraw one out_of_scope citing the principle, or reconcile)"
                 )
-    errors = _lint_errors(results)
+    errors = _lint_errors(results) + principle_errors
     warnings = [
         (r.need.id, w) for r in sorted(results, key=lambda x: x.need.id) for w in r.warnings
-    ]
+    ] + principle_warnings
     # Decision drift (keyed by the decision id, not a need): a decision left serving only
     # withdrawn/non-product needs is engineering with no live product reason; a decision decided
     # under a principle that was revised later comes back up (the same ripple a withdrawal gets).
@@ -558,6 +575,8 @@ def cmd_add(args: argparse.Namespace) -> int:
                 file=args.file,
                 revised_at=date.today().isoformat(),
                 scope=args.scope,
+                implemented_in=args.implemented_in,
+                proofs=tuple(args.principle_proofs or ()),
                 sources=sources,
                 expect_sha=args.expect_sha,
                 dry_run=args.dry_run,

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/cli/render.py

@@ -18,6 +18,7 @@ from ..model import (
     Need,
     NeedResult,
     NeedState,
+    PrincipleState,
     Release,
     Role,
     ears_shape,
@@ -290,15 +291,36 @@ def render_principles(reports: list[PrincipleReport]) -> str:
         a = rep.principle
         rev = f"revised {a.revised_at}" if a.revised_at else "undated"
         scope = "" if a.scope == "product" else f"[{a.scope}] "
-        out.append(f"  {a.id:<6} {scope}{rev}  {a.text}")
+        flag = "⚠ " if rep.state in (PrincipleState.VIOLATED, PrincipleState.BROKEN) else ""
+        out.append(f"  {a.id:<6} {flag}{rep.state.value.upper():<9} {scope}{rev}  {a.text}")
+        if a.implemented_in:
+            out.append(f"        implemented in: {a.implemented_in}")
         if rep.declined:
             out.append(f"        declined: {', '.join(n.id for n in rep.declined)}")
         if rep.stale:
             ids = ", ".join(n.id for n in rep.stale)
             out.append(f"        ⚠ decided before the latest revision: {ids} — re-review")
+    tally = _principle_tally(reports)
+    if tally:
+        out.append(f"  — {tally}")
     return "\n".join(out)
 
 
+def _principle_tally(reports: list[PrincipleReport]) -> str:
+    """A per-scope ENFORCED/STATED/… count line, scopes and states in declared enum order (#89)."""
+    by_scope: dict[str, dict[PrincipleState, int]] = {}
+    for rep in reports:
+        counts = by_scope.setdefault(rep.principle.scope, {})
+        counts[rep.state] = counts.get(rep.state, 0) + 1
+    parts: list[str] = []
+    for scope, counts in by_scope.items():
+        inner = ", ".join(
+            f"{counts[s]} {s.value}" for s in PrincipleState if counts.get(s)
+        )
+        parts.append(f"{scope}: {inner}")
+    return "  ·  ".join(parts)
+
+
 def render_contradictions(contras: list[Contradiction]) -> str:
     """Unresolved contradictions on the board: two needs in tension the vision has not decided."""
     out = ["\ncontradictions (two needs in tension — the vision has not decided):"]

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/loader.py

@@ -344,10 +344,21 @@ def _role(raw: object, where: str) -> Role:
 
 
 def _principle(raw: object, where: str) -> Principle:
-    """Parse one ``principles:`` entry — a product commitment with its provenance."""
+    """Parse one ``principles:`` entry — a product commitment with its provenance and guards."""
     tbl = _as_mapping(raw, where)
+    pid = _as_str(tbl.get("id"), f"{where}.id")
+    proofs = tuple(
+        _as_str(p, f"{where}.proofs[{i}]")
+        for i, p in enumerate(_as_list(tbl.get("proofs"), f"{where}.proofs"))
+    )
+    for p in proofs:
+        if p.split(":", 1)[0] == "need":
+            raise LoaderError(
+                f"principle {pid!r}: proof {p!r} is a need reference — a principle guards the "
+                "code, it does not wait on a need to settle (that inverts the OST)"
+            )
     return Principle(
-        id=_as_str(tbl.get("id"), f"{where}.id"),
+        id=pid,
         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"),
@@ -355,6 +366,8 @@ def _principle(raw: object, where: str) -> Principle:
             _source(s, f"{where}.sources[{i}]")
             for i, s in enumerate(_as_list(tbl.get("sources"), f"{where}.sources"))
         ),
+        implemented_in=_opt_str(tbl.get("implemented_in"), f"{where}.implemented_in"),
+        proofs=proofs,
     )
 
 

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/model.py

@@ -48,6 +48,23 @@ class NeedState(StrEnum):
     UNRESOLVED = "unresolved"  # a proof's source could not be read (e.g. sibling repo absent)
 
 
+class PrincipleState(StrEnum):
+    """Whether a principle's proofs show the code still obeys it (#89).
+
+    A principle proof is a *guard against regression*, the mirror of a need proof's *progress toward*
+    an outcome: a failing need proof is "not yet", but a failing principle guard is "the code
+    contradicts this stance right now" — exactly the tokens.css event where a reversed rule's old
+    wording lived on for months. So a failing guard is VIOLATED, never merely PENDING, and the board
+    cannot read a contradicted principle as green.
+    """
+
+    ENFORCED = "enforced"  # every proof resolved green — the code demonstrably obeys it
+    STATED = "stated"  # no active guard (no proofs, or only declared-pending ones) — honest, allowed
+    VIOLATED = "violated"  # a guard ran and failed — the code contradicts the stance now
+    BROKEN = "broken"  # a proof or implemented_in locator resolves to nothing — lint fails
+    UNRESOLVED = "unresolved"  # a proof's source could not be read (e.g. sibling repo absent)
+
+
 class Answer(StrEnum):
     """Which way a settled question resolved — the research board's direction axis.
 
@@ -169,6 +186,13 @@ class Principle:
     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.
+
+    ``proofs`` tie the principle to the guard tests that prove the code still obeys it, resolved by
+    the same adapters as a need's proofs, and ``implemented_in`` points at the one place the values
+    live (e.g. a tokens file) — a pointer, not a copy, so the hex/font values stay in code. Together
+    they give the principle a :class:`PrincipleState` (ENFORCED / STATED / VIOLATED / BROKEN); a
+    principle may not carry a ``need:`` proof — it guards the code, it does not wait on a need to
+    settle — and it still never enters coverage or the plan.
     """
 
     id: str
@@ -176,6 +200,8 @@ class Principle:
     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
+    implemented_in: str | None = None  # locator to the ONE place the values live; a pointer, not a copy (#89)
+    proofs: tuple[str, ...] = ()  # guard-test locators, resolved by the same adapters as needs (#89)
 
 
 @dataclass(frozen=True)

{prodc-0.4.4 → prodc-0.4.5}/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, group_state, principle_report, state_priority
+from .status import active_decisions, group_state, state_priority
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -156,15 +156,15 @@ def render_markdown(
         out += [
             "## Principles (the vision — held as given)",
             "",
-            "| principle | scope | stated | needs declined under it |",
-            "|---|---|---|---|",
+            "| principle | scope | state | stated | needs declined under it |",
+            "|---|---|---|---|---|",
         ]
-        for rep in principle_report(list(model.needs), list(model.principles)):
+        for rep in board.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.scope} "
+                f"| {rep.principle.id}: {text} | {rep.principle.scope} | {rep.state.value.upper()} "
                 f"| {rep.principle.revised_at or '—'} | {declined}{stale} |"
             )
         out.append("")

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/status.py

@@ -23,6 +23,7 @@ from .model import (
     NeedResult,
     NeedState,
     Principle,
+    PrincipleState,
     ProofState,
     Release,
     Role,
@@ -658,13 +659,48 @@ def role_report(
     return coverage, unroled
 
 
+def principle_state(principle: Principle, adapters: dict[str, Adapter]) -> PrincipleState:
+    """Resolve a principle's guards into its enforced/stated/violated/broken state (#89).
+
+    A principle proof is a guard against regression, so its ``ProofState`` reads differently from a
+    need's (:class:`~prodc.model.PrincipleState` says why). Using :attr:`ProofResult.declared` to tell
+    a declared-but-inactive guard from one that actually ran and failed:
+
+    - ``implemented_in`` set but not resolving, or any proof BROKEN → **BROKEN** (lint fails).
+    - any proof UNRESOLVED → **UNRESOLVED** (a source could not be read).
+    - a proof PENDING with ``declared=False`` (a results artifact shows it failing) → **VIOLATED**.
+    - no proofs, or only DELIVERED-or-declared-pending guards and not all green → **STATED** (honest).
+    - every proof DELIVERED → **ENFORCED**.
+
+    ``implemented_in`` is a pointer, not evidence: it can only make a principle BROKEN (a dangling
+    locator), never ENFORCED.
+    """
+    impl_broken = (
+        principle.implemented_in is not None
+        and _resolve_proof(principle.implemented_in, adapters).state is ProofState.BROKEN
+    )
+    results = [_resolve_proof(loc, adapters) for loc in principle.proofs]
+    if not principle.proofs:
+        return PrincipleState.BROKEN if impl_broken else PrincipleState.STATED
+    if impl_broken or any(r.state is ProofState.BROKEN for r in results):
+        return PrincipleState.BROKEN
+    if any(r.state is ProofState.UNRESOLVED for r in results):
+        return PrincipleState.UNRESOLVED
+    if any(r.state is ProofState.PENDING and not r.declared for r in results):
+        return PrincipleState.VIOLATED  # a guard ran and failed — the code contradicts the stance
+    if all(r.state is ProofState.DELIVERED for r in results):
+        return PrincipleState.ENFORCED
+    return PrincipleState.STATED  # some declared-pending guards, none failing — honestly not yet active
+
+
 @dataclass(frozen=True)
 class PrincipleReport:
-    """One principle and the decisions that rest on it — the ripple, made visible."""
+    """One principle, its enforcement state, and the decisions that rest on it — the ripple made visible."""
 
     principle: Principle
     declined: tuple[Need, ...]  # needs withdrawn citing this principle
     stale: tuple[Need, ...]  # of those, decided before the principle's latest revision — re-review
+    state: PrincipleState = PrincipleState.STATED  # enforced/stated/violated/broken (#89)
 
 
 def _decided_before(decided: str, revised: str | None) -> bool:
@@ -681,13 +717,19 @@ def _decided_before(decided: str, revised: str | None) -> bool:
         return False
 
 
-def principle_report(needs: list[Need], principles: list[Principle]) -> list[PrincipleReport]:
-    """Each declared principle with the needs withdrawn under it, and which of those are stale.
+def principle_report(
+    needs: list[Need],
+    principles: list[Principle],
+    adapters: dict[str, Adapter] | None = None,
+) -> list[PrincipleReport]:
+    """Each declared principle with its enforcement state, the needs withdrawn under it, and the stale ones.
 
     Reads the *whole* need list, withdrawn needs included — a declined need is off the board, so
     the board-filtered list would hide exactly what this reports. A decision is stale when the
     withdrawal is dated before the principle's ``revised_at``: the frame it was judged against has
     changed since, so it comes back up for re-review. Records-only — prodc flags, the PM re-decides.
+    When ``adapters`` are given, each principle also carries its :func:`principle_state` (#89); without
+    them the state defaults to STATED (a caller that has no proof adapters, e.g. a plain ripple view).
     """
     by_principle: dict[str, list[Need]] = {a.id: [] for a in principles}
     for n in needs:
@@ -701,7 +743,8 @@ def principle_report(needs: list[Need], principles: list[Principle]) -> list[Pri
             for n in declined
             if n.withdrawn is not None and _decided_before(n.withdrawn.date, a.revised_at)
         ]
-        out.append(PrincipleReport(a, tuple(declined), tuple(stale)))
+        state = principle_state(a, adapters) if adapters is not None else PrincipleState.STATED
+        out.append(PrincipleReport(a, tuple(declined), tuple(stale), state))
     return out
 
 

{prodc-0.4.4 → prodc-0.4.5}/src/prodc/writer.py

@@ -915,6 +915,8 @@ def add_principle(
     file: str,
     revised_at: str,
     scope: str = "product",
+    implemented_in: str | None = None,
+    proofs: tuple[str, ...] = (),
     sources: tuple[Source, ...] = (),
     expect_sha: str | None = None,
     dry_run: bool,
@@ -948,6 +950,10 @@ def add_principle(
     if scope != "product":
         entry["scope"] = scope  # written only when non-default, to keep the common case clean
     entry["revised_at"] = revised_at
+    if implemented_in is not None:
+        entry["implemented_in"] = implemented_in
+    if proofs:
+        entry["proofs"] = list(proofs)
     if sources:
         entry["sources"] = [_source_dict(s) for s in sources]
     principles.append(entry)

{prodc-0.4.4 → prodc-0.4.5}/tests/test_principles.py

@@ -7,15 +7,32 @@ it rests on; revising that principle later flags the decision for re-review (the
 from __future__ import annotations
 
 import json
+from dataclasses import dataclass
 from datetime import date
 from pathlib import Path
 
 import pytest
 
+from prodc.adapters import Adapter, ProofResult
 from prodc.config import Config
 from prodc.loader import LoaderError, load
-from prodc.model import Principle, Source, SourceKind
-from prodc.status import principle_report
+from prodc.model import Principle, PrincipleState, ProofState, Source, SourceKind
+from prodc.status import principle_report, principle_state
+
+
+@dataclass(frozen=True)
+class _Stub:
+    """Resolves any payload to a fixed ProofResult — a per-adapter test double."""
+
+    result: ProofResult
+
+    def resolve(self, payload: str) -> ProofResult:
+        _ = payload
+        return self.result
+
+
+def _adapter(state: ProofState, *, declared: bool) -> dict[str, Adapter]:
+    return {"g": _Stub(ProofResult(state, declared=declared, detail="stub"))}
 
 _TOML = """
 [prodc]
@@ -179,6 +196,64 @@ def test_add_principle_writes_scope(tmp_path: Path) -> None:
     assert next(p for p in model.principles if p.id == "P-9").scope == "visual"
 
 
+# --- enforced / stated / violated / broken (#89) ----------------------------
+
+
+def _p(**kw: object) -> Principle:
+    return Principle(id="P-1", text="colour is load-bearing", **kw)  # type: ignore[arg-type]
+
+
+def test_no_proofs_is_stated() -> None:
+    # a principle with no guards is honestly STATED — allowed, never a gate failure.
+    assert principle_state(_p(), _adapter(ProofState.DELIVERED, declared=True)) is PrincipleState.STATED
+
+
+def test_all_proofs_delivered_is_enforced() -> None:
+    p = _p(proofs=("g:noPurple",))
+    assert principle_state(p, _adapter(ProofState.DELIVERED, declared=True)) is PrincipleState.ENFORCED
+
+
+def test_failing_guard_with_results_is_violated() -> None:
+    # the trap: a guard that ran and FAILED (results artifact present, not declared) means the code
+    # contradicts the principle NOW — VIOLATED, never a mere STATED/PENDING. "The board cannot lie."
+    p = _p(proofs=("g:noPurple",))
+    assert principle_state(p, _adapter(ProofState.PENDING, declared=False)) is PrincipleState.VIOLATED
+
+
+def test_declared_pending_guard_is_stated_not_violated() -> None:
+    # a guard that is only declared (e.g. @pending, no results) is not yet active — STATED, not VIOLATED.
+    p = _p(proofs=("g:noPurple",))
+    assert principle_state(p, _adapter(ProofState.PENDING, declared=True)) is PrincipleState.STATED
+
+
+def test_broken_proof_is_broken() -> None:
+    p = _p(proofs=("g:noPurple",))
+    assert principle_state(p, _adapter(ProofState.BROKEN, declared=False)) is PrincipleState.BROKEN
+
+
+def test_dangling_implemented_in_is_broken_even_without_proofs() -> None:
+    p = _p(implemented_in="g:tokens.css")
+    assert principle_state(p, _adapter(ProofState.BROKEN, declared=False)) is PrincipleState.BROKEN
+
+
+def test_need_proof_on_principle_rejected(tmp_path: Path) -> None:
+    needs = "principles:\n  - id: P-1\n    text: a principle\n    proofs:\n      - 'need:N-1@yes'\n"
+    with pytest.raises(LoaderError, match="guards the code, it does not wait on a need"):
+        load(Config.load(_project(tmp_path, needs=needs)))
+
+
+def test_lint_hard_fails_broken_principle(tmp_path: Path) -> None:
+    import argparse
+
+    from prodc.cli.commands import cmd_lint
+
+    # a principle whose only proof is an unresolvable locator (no 'ghost' adapter) is BROKEN.
+    needs = "principles:\n  - id: P-1\n    text: a principle\n    proofs:\n      - 'ghost:x'\n"
+    cfg_path = _project(tmp_path, needs=needs)
+    args = argparse.Namespace(config=str(cfg_path), strict=False, json=False)
+    assert cmd_lint(args) == 1
+
+
 # --- principle_report (declined / stale) ------------------------------------