prodc 0.4.4__tar.gz → 0.4.6__tar.gz

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

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

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

@@ -115,6 +115,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
             ),
             "proofs": list(need.proofs),
             "contradicts": list(need.contradicts),
+            "tags": list(need.tags),
             "detail": list(r.detail),
             "warnings": list(r.warnings),
             "attestation": (
@@ -157,6 +158,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
         "product": need.product,
         "draft": need.draft,
         "contradicts": list(need.contradicts),
+        "tags": list(need.tags),
         "answer": need.answer.value if need.answer else None,
         "withdrawn": (
             {
@@ -248,5 +250,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.6}/src/prodc/cli/app.py

@@ -67,6 +67,12 @@ def main(argv: list[str] | None = None) -> int:
         metavar="ID",
         help="scope the board + coverage to the needs serving one goal",
     )
+    st.add_argument(
+        "--tag",
+        default=None,
+        metavar="TAG",
+        help="scope the board + coverage to the needs carrying one tag (#80)",
+    )
     st.add_argument(
         "--columns",
         default=None,
@@ -188,6 +194,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.6}/src/prodc/cli/commands.py

@@ -24,11 +24,12 @@ from ..dedup import (
     VariantGroup,
     duplicate_pairs,
     matches_for,
+    tag_warnings,
     variant_suggestions,
     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 +230,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 +267,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).
@@ -271,6 +289,15 @@ def cmd_lint(args: argparse.Namespace) -> int:
                 f"decided {d.decided_at} under principle {pid}, revised later — re-review this solution",
             )
         )
+    # Tag hygiene (#80): the flat tag space is undeclared, so flag singletons, near-duplicate
+    # spellings, and a tag standing in for a declared goal/role/release/client (structure hiding).
+    structural_ids = (
+        {g.id for g in model.goals}
+        | {p.id for p in model.roles}
+        | {r.id for r in model.releases}
+        | {n.client for n in needs if n.client is not None}
+    )
+    warnings += tag_warnings(needs, structural_ids, cfg.duplicate_threshold)
     if args.json:
         print(
             json.dumps(
@@ -314,6 +341,8 @@ def cmd_status(args: argparse.Namespace) -> int:
         needs = applicable_needs(needs, args.client)
     if args.goal:
         needs = [n for n in needs if n.goal == args.goal]
+    if args.tag:
+        needs = [n for n in needs if args.tag in n.tags]
     if args.stale is not None:
         today = date.today()
         needs = [
@@ -558,6 +587,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.6}/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):"]
@@ -400,6 +422,8 @@ def render_show(
         lines.append(f"  children: {rendered}")
     if need.contradicts:
         lines.append(f"  contradicts: {', '.join(need.contradicts)}")
+    if need.tags:
+        lines.append(f"  tags: {', '.join(need.tags)}")
     if need.seam:
         lines.append(f"  seam: {', '.join(need.seam)}")
     if need.proofs:

{prodc-0.4.4 → prodc-0.4.6}/src/prodc/dedup.py

@@ -237,3 +237,35 @@ def who_variants(needs: list[Need], threshold: float) -> list[WhoVariant]:
             out.append(WhoVariant(client, tuple(sorted(members)), tuple(ids)))
     out.sort(key=lambda v: (v.client or "", v.whos))
     return out
+
+
+def tag_warnings(
+    needs: list[Need], structural_ids: set[str], threshold: float
+) -> list[tuple[str, str]]:
+    """Keep the flat tag space from rotting (#80): singletons, near-dup spellings, hidden structure.
+
+    Tags are undeclared and many-to-many, so nothing stops a typo (`search` vs `searching`) or a
+    one-off from accumulating. Three cheap hygiene signals, each a warning keyed by the tag:
+    a tag equal to a declared goal/role/release/client id ("structure hiding in a tag" — use the
+    first-class field instead), a singleton (one need only — a likely typo or a tag not worth it),
+    and a near-duplicate spelling of another tag (same :func:`similarity` the dedup checks use).
+    """
+    counts: dict[str, int] = {}
+    for n in needs:
+        for t in n.tags:
+            counts[t] = counts.get(t, 0) + 1
+    out: list[tuple[str, str]] = []
+    tags = sorted(counts)
+    for t in tags:
+        if t in structural_ids:
+            out.append(
+                (t, "tag equals a declared goal/role/release/client id — use that field, not a tag")
+            )
+        elif counts[t] == 1:
+            out.append((t, "tag used on only one need — a singleton (likely a typo or not worth a tag)"))
+    for i in range(len(tags)):
+        for j in range(i + 1, len(tags)):
+            a, b = tags[i], tags[j]
+            if _normalise(a) != _normalise(b) and similarity(a, b) >= threshold:
+                out.append((a, f"tag may be a near-duplicate spelling of {b!r}"))
+    return out

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

@@ -278,6 +278,10 @@ def _need(
         _as_str(c, f"{where}.contradicts[{i}]")
         for i, c in enumerate(_as_list(tbl.get("contradicts"), f"{where}.contradicts"))
     )
+    tags = tuple(
+        _as_str(t, f"{where}.tags[{i}]")
+        for i, t in enumerate(_as_list(tbl.get("tags"), f"{where}.tags"))
+    )
     if children and proofs:
         raise LoaderError(
             f"{where} ({nid}): a flow (need with children) proves its steps via the "
@@ -308,6 +312,7 @@ def _need(
         not_duplicate_of=not_duplicate_of,
         not_variant_of=not_variant_of,
         contradicts=contradicts,
+        tags=tags,
         importance_set_at=importance_set_at,
         draft=draft,
         draft_added=draft_added,
@@ -344,10 +349,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 +371,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.6}/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)
@@ -324,6 +350,7 @@ class Need:
     contradicts: tuple[
         str, ...
     ] = ()  # ids of needs this one opposes; symmetric, a principle decides
+    tags: tuple[str, ...] = ()  # flat, many-to-many, stateless labels — a filter axis, not a group (#80)
 
     @property
     def is_variant(self) -> bool:

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

@@ -46,7 +46,7 @@ _SCALAR_FIELDS = frozenset(
         "draft",
     }
 )
-_LIST_FIELDS = frozenset({"proofs", "children", "contradicts"})
+_LIST_FIELDS = frozenset({"proofs", "children", "contradicts", "tags"})
 
 # Source-kind aliases accepted on write (old names → the primary/secondary/assumption ladder),
 # normalised so new files use the current vocabulary even when an author types the old kind.
@@ -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.6}/tests/test_dedup.py

@@ -8,7 +8,7 @@ from pathlib import Path
 import pytest
 
 from prodc.config import Config, ConfigError
-from prodc.dedup import duplicate_pairs, matches_for, similarity
+from prodc.dedup import duplicate_pairs, matches_for, similarity, tag_warnings
 from prodc.model import Need
 
 
@@ -228,3 +228,20 @@ def test_score_prune_matches_brute_force() -> None:
                 if s >= threshold:
                     brute[frozenset((needs[i].id, needs[j].id))] = round(s, 10)
         assert got == brute, f"mismatch at threshold {threshold}"
+
+
+def test_tag_warnings_singleton_nearspelling_and_structure() -> None:
+    needs = [
+        _n("N-1", "a", tags=("search", "searching", "onboarding")),
+        _n("N-2", "b", tags=("search", "onboarding")),
+        _n("N-3", "c", tags=("search", "G-1")),  # G-1 is a declared goal id
+    ]
+    warns = tag_warnings(needs, structural_ids={"G-1"}, threshold=0.4)
+    msgs = {(t, m) for t, m in warns}
+    tags_warned = {t for t, _ in warns}
+    # G-1 is structural, searching is a singleton, search is used 4x (no singleton warning)
+    assert any(t == "G-1" and "declared goal/role/release/client" in m for t, m in msgs)
+    assert any(t == "searching" and "singleton" in m for t, m in msgs)
+    assert any("near-duplicate spelling" in m for _, m in msgs)
+    assert "search" not in {t for t, m in msgs if "singleton" in m}  # 4 uses, not a singleton
+    assert tags_warned  # sanity

{prodc-0.4.4 → prodc-0.4.6}/tests/test_loader.py

@@ -262,6 +262,16 @@ def test_goals_loaded_and_need_traces_up(tmp_path: Path) -> None:
     assert model.needs[0].goal == "G-1"
 
 
+def test_need_loads_tags(tmp_path: Path) -> None:
+    # #80: tags are a flat, many-to-many label list on a need.
+    cfg = _config(
+        tmp_path,
+        ("a.yaml", "needs:\n  - id: N-1\n    text: a need\n    tags: [search, onboarding]\n"),
+    )
+    (need,) = load_needs(cfg)
+    assert need.tags == ("search", "onboarding")
+
+
 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

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

{prodc-0.4.4 → prodc-0.4.6}/tests/test_writer.py

@@ -302,6 +302,14 @@ def test_children_append_bare_id(tmp_path: Path) -> None:
     assert [(c.id, c.step) for c in flow.children] == [("N-2", None), ("N-3", None)]
 
 
+def test_tags_append(tmp_path: Path) -> None:
+    # #80: tags are a plain string list; `tags+=X` appends like proofs.
+    cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: a need\n    tags: [search]\n")
+    set_field(cfg, "N-1", "tags+=onboarding", expect_sha=None, dry_run=False)
+    need = next(n for n in load(cfg).needs if n.id == "N-1")
+    assert need.tags == ("search", "onboarding")
+
+
 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'"):