prodc 0.2.0__py3-none-any.whl

prodc/__init__.py

@@ -0,0 +1,3 @@
+"""prodc: product management as code."""
+
+__version__ = "0.1.0"

prodc/adapters.py

@@ -0,0 +1,194 @@
+"""Proof adapters: resolve a locator payload to a :class:`ProofState`.
+
+An adapter reads a repo as it already is (Gherkin titles, pytest node ids). Status
+comes from a test-results artifact (cucumber-json / junit) when configured and
+present; otherwise it reports a *declared* state (from tags or existence) and says so.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol, cast
+
+from .model import ProofState
+
+_TAG_RE = re.compile(r"@[\w\-.]+")
+_SCENARIO_RE = re.compile(r"^\s*(?:Scenario|Scenario Outline):\s*(.*?)\s*$")
+
+
+def _steps_passed(steps: list[object]) -> bool:
+    """A scenario passes iff every step's result status is 'passed' (cucumber-json)."""
+    for step in steps:
+        if not isinstance(step, dict):
+            return False
+        result = cast("dict[str, object]", step).get("result")
+        status = cast("dict[str, object]", result).get("status") if isinstance(result, dict) else None
+        if status != "passed":
+            return False
+    return True
+
+
+@dataclass(frozen=True)
+class ProofResult:
+    state: ProofState
+    declared: bool  # True when the state rests on tags/existence, not a results artifact
+    detail: str
+
+
+class Adapter(Protocol):
+    def resolve(self, payload: str) -> ProofResult: ...
+
+
+@dataclass(frozen=True)
+class _Scenario:
+    file: str
+    title: str
+    tags: frozenset[str]
+
+
+class GherkinAdapter:
+    """Resolves ``file#Scenario title`` or ``tag:@US-050`` against feature files."""
+
+    def __init__(
+        self,
+        root: Path,
+        paths: list[str],
+        delivered_tags: list[str],
+        pending_tags: list[str],
+        results: str | None,
+    ) -> None:
+        self._root = root
+        self._paths = paths
+        self._delivered = frozenset(delivered_tags)
+        self._pending = frozenset(pending_tags)
+        self._results_path = results
+        self._scenarios: list[_Scenario] | None = None
+        self._results: dict[str, bool] | None = None
+
+    def _load(self) -> list[_Scenario]:
+        if self._scenarios is not None:
+            return self._scenarios
+        found: list[_Scenario] = []
+        for pattern in self._paths:
+            for fp in sorted(self._root.glob(pattern)):
+                pending: set[str] = set()
+                for line in fp.read_text(encoding="utf-8").splitlines():
+                    stripped = line.strip()
+                    if stripped.startswith("@"):
+                        pending |= set(_TAG_RE.findall(stripped))
+                        continue
+                    m = _SCENARIO_RE.match(line)
+                    if m:
+                        found.append(
+                            _Scenario(fp.name, m.group(1), frozenset(pending))
+                        )
+                        pending = set()
+                    elif stripped and not stripped.startswith("#"):
+                        pending = set()
+        self._scenarios = found
+        return found
+
+    def _load_results(self) -> dict[str, bool]:
+        """Map scenario name -> passed, from a cucumber-json report if configured."""
+        if self._results is not None:
+            return self._results
+        out: dict[str, bool] = {}
+        if self._results_path:
+            rp = self._root / self._results_path
+            if rp.exists():
+                data: object = json.loads(rp.read_text(encoding="utf-8"))
+                if isinstance(data, list):
+                    for feature in cast("list[object]", data):
+                        if not isinstance(feature, dict):
+                            continue
+                        elements = cast("dict[str, object]", feature).get("elements")
+                        if not isinstance(elements, list):
+                            continue
+                        for el in cast("list[object]", elements):
+                            if not isinstance(el, dict):
+                                continue
+                            el_d = cast("dict[str, object]", el)
+                            name = el_d.get("name")
+                            steps = el_d.get("steps")
+                            if isinstance(name, str) and isinstance(steps, list):
+                                out[name] = _steps_passed(cast("list[object]", steps))
+        self._results = out
+        return out
+
+    def resolve(self, payload: str) -> ProofResult:
+        scenarios = self._load()
+        if payload.startswith("tag:"):
+            want = payload[4:]
+            matches = [s for s in scenarios if want in s.tags]
+        else:
+            file_part, _, title = payload.partition("#")
+            matches = [
+                s for s in scenarios if s.title == title and (not file_part or s.file == file_part)
+            ]
+        if not matches:
+            return ProofResult(ProofState.BROKEN, False, f"no scenario matches '{payload}'")
+
+        results = self._load_results()
+        if results:
+            states = [results.get(s.title) for s in matches]
+            if all(v is True for v in states):
+                return ProofResult(ProofState.DELIVERED, False, "results: passed")
+            if any(v is False for v in states):
+                return ProofResult(ProofState.PENDING, False, "results: failing")
+            # matched scenarios absent from the report → declared only
+        tags: frozenset[str] = frozenset()
+        for s in matches:
+            tags |= s.tags
+        if tags & self._delivered:
+            return ProofResult(ProofState.DELIVERED, True, "tagged delivered")
+        if tags & self._pending:
+            return ProofResult(ProofState.PENDING, True, "tagged pending")
+        return ProofResult(ProofState.PENDING, True, "found, untagged")
+
+
+class PytestAdapter:
+    """Resolves ``path::test_name`` by existence, upgraded by a junit report if given."""
+
+    def __init__(self, root: Path, results: str | None) -> None:
+        self._root = root
+        self._results_path = results
+        self._results: dict[str, bool] | None = None
+
+    def _load_results(self) -> dict[str, bool]:
+        if self._results is not None:
+            return self._results
+        out: dict[str, bool] = {}
+        if self._results_path:
+            rp = self._root / self._results_path
+            if rp.exists():
+                tree = ET.parse(rp)
+                for case in tree.iter("testcase"):
+                    name = case.get("name", "")
+                    failed = any(c.tag in ("failure", "error") for c in case)
+                    skipped = any(c.tag == "skipped" for c in case)
+                    if name:
+                        out[name] = not failed and not skipped
+        self._results = out
+        return out
+
+    def resolve(self, payload: str) -> ProofResult:
+        file_part, _, node = payload.partition("::")
+        func = node.split("[")[0]  # strip parametrisation
+        fp = self._root / file_part
+        if not fp.exists():
+            return ProofResult(ProofState.BROKEN, False, f"no file '{file_part}'")
+        if func and f"def {func}" not in fp.read_text(encoding="utf-8"):
+            return ProofResult(ProofState.BROKEN, False, f"no test '{func}' in {file_part}")
+        results = self._load_results()
+        if func in results:
+            ok = results[func]
+            return ProofResult(
+                ProofState.DELIVERED if ok else ProofState.PENDING,
+                False,
+                "junit: passed" if ok else "junit: failing",
+            )
+        return ProofResult(ProofState.DELIVERED, True, "test exists")

prodc/cli.py

@@ -0,0 +1,224 @@
+"""``prodc`` command line: one verb, ``status`` — the board.
+
+Prints the gap between needs and what the test suite proves, sorted by what needs
+attention first. Exit 1 on a BROKEN proof; ``--strict`` also on an opinion. A HOLE
+never fails — it is the honest gap you want people to keep writing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .config import Config, ConfigError
+from .loader import LoaderError, load_needs
+from .model import Need, NeedResult, NeedState, SourceKind
+from .status import Summary, resolve, summarize
+
+_LABEL = {
+    NeedState.DELIVERED: "DELIVERED",
+    NeedState.PENDING: "PENDING",
+    NeedState.HOLE: "HOLE",
+    NeedState.BROKEN: "BROKEN",
+}
+
+
+def _priority(r: NeedResult) -> int:
+    if r.need.must and r.state is NeedState.HOLE:
+        return 0
+    return {
+        NeedState.BROKEN: 1,
+        NeedState.PENDING: 2,
+        NeedState.HOLE: 3,
+        NeedState.DELIVERED: 4,
+    }[r.state]
+
+
+# Warrant strength, strongest first: interview > artifact > internal (Torres).
+_WARRANT_ORDER = (SourceKind.INTERVIEW, SourceKind.ARTIFACT, SourceKind.INTERNAL)
+
+
+def _warrant(need: Need) -> str:
+    """The warrant column: the strongest source kind, or 'opinion' when unsourced."""
+    if need.is_opinion:
+        return "opinion"
+    kinds = {s.kind for s in need.sources}
+    strongest = next(k for k in _WARRANT_ORDER if k in kinds)
+    if strongest is SourceKind.INTERVIEW:
+        who = next((s.who for s in need.sources if s.kind is SourceKind.INTERVIEW and s.who), None)
+        return f"interview:{who}" if who else "interview"
+    return strongest.value
+
+
+def _summary_line(s: Summary) -> str:
+    """The leading gap-count line: what needs attention, and overall coverage."""
+    parts: list[str] = []
+    if s.must_hole:
+        parts.append(f"{s.must_hole} must-HOLE")
+    if s.broken:
+        parts.append(f"{s.broken} BROKEN")
+    if s.pending:
+        parts.append(f"{s.pending} PENDING")
+    if s.hole - s.must_hole:
+        parts.append(f"{s.hole - s.must_hole} HOLE")
+    if s.opinion:
+        parts.append(f"{s.opinion} opinion")
+    gaps = "  ·  ".join(parts) if parts else "no gaps"
+    return f"gaps: {gaps}    coverage {s.delivered}/{s.total} ({round(s.coverage * 100)}%)"
+
+
+def _render(results: list[NeedResult]) -> str:
+    groups: dict[str, list[NeedResult]] = {}
+    for r in results:
+        groups.setdefault(r.need.who or "(unassigned)", []).append(r)
+
+    out: list[str] = []
+    # The Toulmin split: GROUNDS (does a test prove it?) vs WARRANT (user signal it
+    # matters?). A need can be green on one and empty on the other — that gap is the point.
+    out.append(f"  {'':2} {'id':<9} {'GROUNDS':<10}{'':5} {'need':<48}  WARRANT")
+    for who in sorted(groups):
+        rs = sorted(groups[who], key=_priority)
+        label = next((x.need.label for x in rs if x.need.label), None)
+        counts = {s: sum(1 for r in rs if r.state is s) for s in NeedState}
+        head = "  ·  ".join(f"{counts[s]} {_LABEL[s]}" for s in NeedState if counts[s])
+        title = f"{who}" + (f" ({label})" if label else "")
+        out.append(f"\n{title}    {head}")
+        for r in rs:
+            bang = "!!" if r.need.must else "  "
+            star = "*" if r.declared and r.state is NeedState.DELIVERED else " "
+            nm = f"{r.delivered}/{r.total}" if r.total else ""
+            out.append(
+                f"  {bang} {r.need.id:<9} {_LABEL[r.state]:<9}{star} {nm:<5} "
+                f"{r.need.text[:48]:<48}  {_warrant(r.need)}"
+            )
+            for w in r.warnings:
+                out.append(f"       ⚠ {w}")
+    return "\n".join(out)
+
+
+def _to_json(results: list[NeedResult], summary: Summary) -> str:
+    payload = {
+        "summary": {
+            "total": summary.total,
+            "delivered": summary.delivered,
+            "pending": summary.pending,
+            "hole": summary.hole,
+            "must_hole": summary.must_hole,
+            "broken": summary.broken,
+            "opinion": summary.opinion,
+            "coverage": round(summary.coverage, 4),
+        },
+        "needs": [
+            {
+                "id": r.need.id,
+                "who": r.need.who,
+                "text": r.need.text,
+                "must": r.need.must,
+                "state": r.state.value,
+                "grounds": r.state.value,
+                "warrant": _warrant(r.need),
+                "delivered": r.delivered,
+                "total": r.total,
+                "declared": r.declared,
+                "opinion": r.need.is_opinion,
+                "only_internal": r.need.only_internal,
+                "detail": r.detail,
+                "warnings": r.warnings,
+            }
+            for r in results
+        ],
+    }
+    return json.dumps(payload, indent=2)
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    cfg_path = Path(args.config)
+    if not cfg_path.exists():
+        print(f"prodc: no config at {cfg_path}", file=sys.stderr)
+        return 2
+    try:
+        cfg = Config.load(cfg_path)
+        needs = load_needs(cfg)
+    except (ConfigError, LoaderError) as exc:
+        print(f"prodc: {exc}", file=sys.stderr)
+        return 2
+    results = resolve(needs, cfg.adapters)
+    summary = summarize(results)
+
+    if args.json:
+        print(_to_json(results, summary))
+    else:
+        commit = _git_rev(cfg.root)
+        print(f"prodc status — {cfg.root.name}{f' @ {commit}' if commit else ''}")
+        print(_summary_line(summary))
+        print(_render(results))
+
+    return _exit_code(args, summary)
+
+
+def _exit_code(args: argparse.Namespace, summary: Summary) -> int:
+    """Gate: 0 unless a threshold is crossed; HOLE never fails.
+
+    Default fails on any BROKEN; ``--max-dangling N`` tolerates N; ``--min-coverage F``
+    fails when delivered/total < F; ``--strict`` fails on any opinion.
+    """
+    if args.max_dangling is not None:
+        if summary.broken > args.max_dangling:
+            return 1
+    elif summary.broken:
+        return 1
+    if args.min_coverage is not None and summary.coverage < args.min_coverage:
+        return 1
+    if args.strict and summary.opinion:
+        return 1
+    return 0
+
+
+def _git_rev(root: Path) -> str | None:
+    head = root / ".git" / "HEAD"
+    try:
+        ref = head.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if ref.startswith("ref:"):
+        target = root / ".git" / ref[4:].strip()
+        try:
+            return target.read_text(encoding="utf-8").strip()[:7]
+        except OSError:
+            return None
+    return ref[:7]
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="prodc", description="Product management as code.")
+    parser.add_argument("--version", action="version", version=f"prodc {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    st = sub.add_parser("status", help="show the needs board")
+    st.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    st.add_argument("--json", action="store_true", help="machine-readable output")
+    st.add_argument("--strict", action="store_true", help="also exit 1 on opinions")
+    st.add_argument(
+        "--min-coverage",
+        type=float,
+        default=None,
+        metavar="FRAC",
+        help="gate: exit 1 if delivered/total < FRAC (0..1)",
+    )
+    st.add_argument(
+        "--max-dangling",
+        type=int,
+        default=None,
+        metavar="N",
+        help="gate: tolerate up to N broken locators instead of failing on any",
+    )
+    st.set_defaults(func=_cmd_status)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

prodc/config.py

@@ -0,0 +1,75 @@
+"""Load ``prodc.toml``: where the needs live and how each proof adapter resolves."""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import cast
+
+from .adapters import Adapter, GherkinAdapter, PytestAdapter
+
+
+class ConfigError(Exception):
+    pass
+
+
+def _as_dict(value: object, where: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise ConfigError(f"{where}: expected a table")
+    return cast("dict[str, object]", value)
+
+
+def _as_str_list(value: object, where: str) -> list[str]:
+    if not isinstance(value, list):
+        raise ConfigError(f"{where}: expected a list of strings")
+    items = cast("list[object]", value)
+    if not all(isinstance(x, str) for x in items):
+        raise ConfigError(f"{where}: expected a list of strings")
+    return [x for x in items if isinstance(x, str)]
+
+
+@dataclass
+class Config:
+    root: Path
+    need_globs: list[str]
+    adapters: dict[str, Adapter] = field(default_factory=dict[str, Adapter])
+
+    @classmethod
+    def load(cls, path: Path) -> Config:
+        root = path.parent
+        raw = _as_dict(tomllib.loads(path.read_text(encoding="utf-8")), "prodc.toml")
+
+        prodc_tbl = _as_dict(raw.get("prodc", {}), "[prodc]")
+        need_globs = _as_str_list(prodc_tbl.get("needs", []), "[prodc].needs")
+        if not need_globs:
+            raise ConfigError("[prodc].needs must list at least one glob")
+
+        adapters: dict[str, Adapter] = {}
+        proofs = _as_dict(raw.get("proofs", {}), "[proofs]")
+        for name, body in proofs.items():
+            tbl = _as_dict(body, f"[proofs.{name}]")
+            kind = tbl.get("kind")
+            results = tbl.get("results")
+            results_s = results if isinstance(results, str) else None
+            if kind == "gherkin":
+                adapters[name] = GherkinAdapter(
+                    root=root,
+                    paths=_as_str_list(tbl.get("paths", []), f"[proofs.{name}].paths"),
+                    delivered_tags=_as_str_list(
+                        tbl.get("delivered", []), f"[proofs.{name}].delivered"
+                    ),
+                    pending_tags=_as_str_list(
+                        tbl.get("pending", []), f"[proofs.{name}].pending"
+                    ),
+                    results=results_s,
+                )
+            elif kind == "pytest":
+                sub = tbl.get("root", ".")
+                adapters[name] = PytestAdapter(
+                    root=root / (sub if isinstance(sub, str) else "."),
+                    results=results_s,
+                )
+            else:
+                raise ConfigError(f"[proofs.{name}]: unknown kind {kind!r} (gherkin|pytest)")
+        return cls(root=root, need_globs=need_globs, adapters=adapters)

prodc/loader.py

@@ -0,0 +1,141 @@
+"""Load need files (YAML) into :class:`~prodc.model.Need` objects.
+
+A file-level ``who``/``label`` default every need in it; a need may override either.
+IDs are globally unique (children reference ids across files), so a duplicate is a
+:class:`LoaderError`. A flow (need with ``children``) must not also carry ``proofs``.
+"""
+
+from __future__ import annotations
+
+import datetime
+from pathlib import Path
+from typing import cast
+
+import yaml
+
+from .config import Config
+from .model import Need, Source, SourceKind
+
+
+class LoaderError(Exception):
+    pass
+
+
+def _as_mapping(value: object, where: str) -> dict[str, object]:
+    if not isinstance(value, dict):
+        raise LoaderError(f"{where}: expected a mapping")
+    return cast("dict[str, object]", value)
+
+
+def _as_list(value: object, where: str) -> list[object]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise LoaderError(f"{where}: expected a list")
+    return cast("list[object]", value)
+
+
+def _as_str(value: object, where: str) -> str:
+    if not isinstance(value, str):
+        raise LoaderError(f"{where}: expected a string")
+    return value
+
+
+def _opt_str(value: object, where: str) -> str | None:
+    if value is None:
+        return None
+    # A bare ``date: 2026-09-20`` parses as a date, not a string — accept it.
+    if isinstance(value, datetime.date):
+        return value.isoformat()
+    return _as_str(value, where)
+
+
+def _as_bool(value: object, where: str) -> bool:
+    if not isinstance(value, bool):
+        raise LoaderError(f"{where}: expected a boolean")
+    return value
+
+
+def _source(raw: object, where: str) -> Source:
+    tbl = _as_mapping(raw, where)
+    kind_name = _opt_str(tbl.get("kind"), f"{where}.kind") or SourceKind.INTERNAL.value
+    try:
+        kind = SourceKind(kind_name)
+    except ValueError:
+        kinds = "|".join(k.value for k in SourceKind)
+        raise LoaderError(f"{where}.kind: unknown kind {kind_name!r} ({kinds})") from None
+    return Source(
+        kind=kind,
+        who=_opt_str(tbl.get("who"), f"{where}.who"),
+        date=_opt_str(tbl.get("date"), f"{where}.date"),
+        quote=_opt_str(tbl.get("quote"), f"{where}.quote"),
+        locator=_opt_str(tbl.get("locator"), f"{where}.locator"),
+    )
+
+
+def _need(raw: object, where: str, file_who: str | None, file_label: str | None) -> Need:
+    tbl = _as_mapping(raw, where)
+    nid = _as_str(tbl.get("id"), f"{where}.id")
+    text = _as_str(tbl.get("text"), f"{where}.text")
+    must = _as_bool(tbl["must"], f"{where}.must") if "must" in tbl else False
+    who = _opt_str(tbl.get("who"), f"{where}.who") or file_who
+    label = _opt_str(tbl.get("label"), f"{where}.label") or file_label
+
+    sources = tuple(
+        _source(s, f"{where}.sources[{i}]")
+        for i, s in enumerate(_as_list(tbl.get("sources"), f"{where}.sources"))
+    )
+    proofs = tuple(
+        _as_str(p, f"{where}.proofs[{i}]")
+        for i, p in enumerate(_as_list(tbl.get("proofs"), f"{where}.proofs"))
+    )
+    children = tuple(
+        _as_str(c, f"{where}.children[{i}]")
+        for i, c in enumerate(_as_list(tbl.get("children"), f"{where}.children"))
+    )
+    if children and proofs:
+        raise LoaderError(f"{where} ({nid}): a flow (need with children) must not carry proofs")
+
+    return Need(
+        id=nid,
+        text=text,
+        who=who,
+        must=must,
+        sources=sources,
+        proofs=proofs,
+        children=children,
+        label=label,
+    )
+
+
+def _load_file(path: Path, seen: dict[str, Path]) -> list[Need]:
+    where = path.name
+    try:
+        doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise LoaderError(f"{where}: invalid YAML: {exc}") from exc
+    if doc is None:
+        return []
+    tbl = _as_mapping(doc, where)
+    file_who = _opt_str(tbl.get("who"), f"{where}.who")
+    file_label = _opt_str(tbl.get("label"), f"{where}.label")
+
+    out: list[Need] = []
+    for i, raw in enumerate(_as_list(tbl.get("needs"), f"{where}.needs")):
+        need = _need(raw, f"{where}.needs[{i}]", file_who, file_label)
+        prior = seen.get(need.id)
+        if prior is not None:
+            raise LoaderError(f"duplicate need id {need.id!r} in {where} and {prior.name}")
+        seen[need.id] = path
+        out.append(need)
+    return out
+
+
+def load_needs(config: Config) -> list[Need]:
+    """Resolve every need glob in ``config`` to a flat, id-unique list of needs."""
+    needs: list[Need] = []
+    seen: dict[str, Path] = {}
+    for pattern in config.need_globs:
+        for path in sorted(config.root.glob(pattern)):
+            needs.extend(_load_file(path, seen))
+    return needs

prodc/model.py

@@ -0,0 +1,111 @@
+"""The prodc data model: Need, Source, and the derived status states.
+
+Three nouns (Torres): a Need is what a named person wants (an opportunity); a
+Source is its provenance (evidence) — a Need with no Source is an opinion; a proof
+is a locator to a delivery test, resolved by an adapter. Everything else is
+expressed with these: a flow is a Need with children, a persona is ``who``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class SourceKind(StrEnum):
+    """How a need was evidenced, in descending epistemic weight (Torres, Ch. 5)."""
+
+    INTERVIEW = "interview"  # behavioural evidence: a named customer, a date, a verbatim quote
+    ARTIFACT = "artifact"  # documentary: a ticket, doc or email locator
+    INTERNAL = "internal"  # a team member's own assertion — provenance, but not a customer's
+
+
+class ProofState(StrEnum):
+    """The state of a single proof locator, reported by its adapter."""
+
+    DELIVERED = "delivered"  # the test exists and (if a results artifact is present) passes
+    PENDING = "pending"  # declared/planned, not yet green
+    BROKEN = "broken"  # the locator does not resolve to anything
+
+
+class NeedState(StrEnum):
+    """The rolled-up state of a Need (its proofs, or its children)."""
+
+    DELIVERED = "delivered"
+    PENDING = "pending"
+    HOLE = "hole"  # no proof at all — an honest gap, never a build failure
+    BROKEN = "broken"  # a proof locator points at nothing
+
+
+@dataclass(frozen=True)
+class Source:
+    """Where a need came from. Absence of any Source makes the need an opinion."""
+
+    kind: SourceKind
+    who: str | None = None
+    date: str | None = None
+    quote: str | None = None
+    locator: str | None = None
+
+    def warnings(self) -> list[str]:
+        """Soft, Torres-derived hygiene checks — never fail the build."""
+        out: list[str] = []
+        if self.kind is SourceKind.INTERVIEW and not self.quote:
+            out.append("interview source without a verbatim quote")
+        if self.kind is SourceKind.INTERVIEW and not self.who:
+            out.append("interview source without a named person")
+        if self.kind is SourceKind.ARTIFACT and not self.locator:
+            out.append("artifact source without a locator")
+        if not self.date:
+            out.append("source without a date")
+        return out
+
+
+@dataclass(frozen=True)
+class Need:
+    """What a named person wants, with its provenance and its proofs."""
+
+    id: str
+    text: str
+    who: str | None = None
+    must: bool = False
+    sources: tuple[Source, ...] = ()
+    proofs: tuple[str, ...] = ()  # locators, "<adapter>:<payload>"
+    children: tuple[str, ...] = ()  # ids of sub-needs (a flow is a Need with children)
+    label: str | None = None  # free text for the `who`, e.g. "design partner, Sincerely"
+
+    @property
+    def is_opinion(self) -> bool:
+        """No source of any kind = opinion (Torres: an unvalidated desirability assumption)."""
+        return len(self.sources) == 0
+
+    @property
+    def only_internal(self) -> bool:
+        """Sourced, but only by the team's own assertion — not a customer."""
+        return len(self.sources) > 0 and all(s.kind is SourceKind.INTERNAL for s in self.sources)
+
+
+# A leading verb that usually signals a solution-in-disguise, not a need (Torres, Ch. 6).
+SOLUTION_VERBS = (
+    "implement",
+    "add",
+    "build",
+    "create",
+    "support",
+    "integrate",
+    "redesign",
+    "refactor",
+)
+
+
+@dataclass
+class NeedResult:
+    """A resolved need: its state, its proof detail, and any hygiene warnings."""
+
+    need: Need
+    state: NeedState
+    delivered: int = 0
+    total: int = 0
+    declared: bool = False  # true if DELIVERED rests on tags/existence, not a results artifact
+    detail: list[str] = field(default_factory=list[str])
+    warnings: list[str] = field(default_factory=list[str])

prodc/status.py

@@ -0,0 +1,142 @@
+"""Resolve needs into states: the engine behind ``prodc status``.
+
+A leaf's state comes from its proofs; a flow (need with children) aggregates its
+sub-needs. ``HOLE`` (no proof) is deliberately not a failure — it is an honest gap.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .adapters import Adapter, ProofResult
+from .model import (
+    SOLUTION_VERBS,
+    Need,
+    NeedResult,
+    NeedState,
+    ProofState,
+)
+
+
+def _text_warnings(need: Need) -> list[str]:
+    first = need.text.strip().split(" ", 1)[0].lower().rstrip(":")
+    out: list[str] = []
+    if first in SOLUTION_VERBS:
+        out.append(f"text may be a solution in disguise (starts with '{first}')")
+    for src in need.sources:
+        out.extend(src.warnings())
+    return out
+
+
+def _resolve_proof(locator: str, adapters: dict[str, Adapter]) -> ProofResult:
+    name, sep, payload = locator.partition(":")
+    adapter = adapters.get(name)
+    if not sep or adapter is None:
+        return ProofResult(ProofState.BROKEN, False, f"no adapter '{name}' for '{locator}'")
+    return adapter.resolve(payload)
+
+
+class Resolver:
+    def __init__(self, needs: list[Need], adapters: dict[str, Adapter]) -> None:
+        self._by_id = {n.id: n for n in needs}
+        self._adapters = adapters
+        self._cache: dict[str, NeedResult] = {}
+        self._visiting: set[str] = set()
+
+    def resolve_all(self) -> list[NeedResult]:
+        return [self.resolve(n.id) for n in self._by_id.values()]
+
+    def resolve(self, need_id: str) -> NeedResult:
+        if need_id in self._cache:
+            return self._cache[need_id]
+        need = self._by_id[need_id]
+        if need_id in self._visiting:  # cycle — stop and report
+            return NeedResult(need, NeedState.BROKEN, detail=["cycle in children"])
+        self._visiting.add(need_id)
+        result = self._compute(need)
+        self._visiting.discard(need_id)
+        result.warnings = _text_warnings(need) + result.warnings
+        self._cache[need_id] = result
+        return result
+
+    def _compute(self, need: Need) -> NeedResult:
+        if need.children:
+            return self._aggregate_children(need)
+        return self._resolve_leaf(need)
+
+    def _resolve_leaf(self, need: Need) -> NeedResult:
+        if not need.proofs:
+            return NeedResult(need, NeedState.HOLE)
+        results = [_resolve_proof(p, self._adapters) for p in need.proofs]
+        detail = [f"{p} → {r.state.value}{'*' if r.declared else ''} ({r.detail})"
+                  for p, r in zip(need.proofs, results, strict=True)]
+        delivered = sum(1 for r in results if r.state is ProofState.DELIVERED)
+        declared = any(r.declared for r in results if r.state is ProofState.DELIVERED)
+        if any(r.state is ProofState.BROKEN for r in results):
+            state = NeedState.BROKEN
+        elif delivered == len(results):
+            state = NeedState.DELIVERED
+        else:
+            state = NeedState.PENDING
+        return NeedResult(need, state, delivered, len(results), declared, detail)
+
+    def _aggregate_children(self, need: Need) -> NeedResult:
+        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}'")
+                continue
+            cr = self.resolve(cid)
+            child_states.append(cr.state)
+            declared = declared or cr.declared
+        delivered = sum(1 for s in child_states if s is NeedState.DELIVERED)
+        total = len(child_states)
+        if any(s is NeedState.BROKEN for s in child_states):
+            state = NeedState.BROKEN
+        elif total and delivered == total:
+            state = NeedState.DELIVERED
+        elif not child_states or all(s is NeedState.HOLE for s in child_states):
+            state = NeedState.HOLE
+        else:
+            state = NeedState.PENDING
+        detail = [f"{delivered} of {total} sub-needs delivered"]
+        return NeedResult(need, state, delivered, total, declared, detail, warnings)
+
+
+def resolve(needs: list[Need], adapters: dict[str, Adapter]) -> list[NeedResult]:
+    """Resolve every need to a :class:`NeedResult`."""
+    return Resolver(needs, adapters).resolve_all()
+
+
+@dataclass(frozen=True)
+class Summary:
+    """The gap at a glance: how many needs sit in each state, and how many are opinions."""
+
+    total: int
+    delivered: int
+    pending: int
+    hole: int
+    must_hole: int  # a HOLE on a must-have — the top of the board
+    broken: int  # a dangling proof locator
+    opinion: int  # a need with no source of any kind
+
+    @property
+    def coverage(self) -> float:
+        """Fraction of needs that are DELIVERED (0.0 when there are no needs)."""
+        return self.delivered / self.total if self.total else 0.0
+
+
+def summarize(results: list[NeedResult]) -> Summary:
+    """Roll a resolved board up into its gap counts."""
+    by_state = {s: sum(1 for r in results if r.state is s) for s in NeedState}
+    return Summary(
+        total=len(results),
+        delivered=by_state[NeedState.DELIVERED],
+        pending=by_state[NeedState.PENDING],
+        hole=by_state[NeedState.HOLE],
+        must_hole=sum(1 for r in results if r.need.must and r.state is NeedState.HOLE),
+        broken=by_state[NeedState.BROKEN],
+        opinion=sum(1 for r in results if r.need.is_opinion),
+    )

prodc-0.2.0.dist-info/METADATA

@@ -0,0 +1,71 @@
+Metadata-Version: 2.5
+Name: prodc
+Version: 0.2.0
+Summary: Product management as code: personas, flows, and features traced to evidence.
+Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
+Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc
+Project-URL: Changelog, https://gitlab.com/jorgeecardona/prodc/-/blob/main/CHANGELOG.md
+Author-email: Jorge Cardona <jorgeecardona@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# prodc
+
+Product management as code: personas, flows, and features traced to evidence, so a
+product's state is read from the repo instead of chased in meetings.
+
+prodc treats product thinking the way requirements-as-code tools (Doorstop, StrictDoc)
+treat requirements — plain text, in git, with IDs that link to each other — but for the
+artifacts a product person actually works with: **Persona → Flow → Feature → Assumption**,
+each tied to **evidence**. Two rules give it teeth:
+
+- **No evidence link = flagged as opinion.** Every "why" must trace to a user signal
+  (feedback, ticket, interview), or it is marked unsupported.
+- **Status comes from the repo, not from a standup.** "Flow UF-004: 3 of 5 scenarios
+  passing", "Feature F-012: blocked, assumption A-003 has no data" — the report answers
+  "where are we" and "what's blocking" without a meeting.
+
+The lineage is Toulmin's argument model (claim + grounds + warrant): a feature is a claim,
+its evidence is the grounds, its assumptions are the warrant. The same shape safety
+engineering uses for a "safety case", pointed at product decisions.
+
+> Status: v0, early. The data model and the first cross-repo adapter are still being shaped
+> (see `docs/issues/`). Not yet on PyPI.
+
+## Install
+
+```bash
+uv sync          # dependencies
+make install-hooks
+make check       # lint + typecheck + test
+```
+
+## Why not just Doorstop / StrictDoc?
+
+Those track "the system shall…" requirements for auditors in regulated industries. prodc
+tracks personas, flows and features for product decisions, and derives live status from the
+project's own tests. It reads a repo it is pointed at — including existing Gherkin/BDD and
+whatever ID scheme already lives there — rather than asking you to re-author everything in a
+new grammar.
+
+## Layout
+
+- `src/prodc/` — the package (typed; `py.typed`).
+- `docs/issues/` — follow-ups (the `cabildo issues` convention).
+- `Makefile` — `format` / `lint` / `typecheck` / `test` / `check` / `build` / `docs`.
+- `AGENTS.md` — build/test/style/gotchas for coding agents.

prodc-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+prodc/__init__.py,sha256=FrOr-0V0IGRPK-ygMrR6J8D2xni-ML48IhdUyOCXVRc,64
+prodc/adapters.py,sha256=vBn-nKjoAQQhCXoOpd1q-vpQyr-p0xwZkPDiLA4G9Nc,7607
+prodc/cli.py,sha256=gKXD-w_43lrLdhazL_mHm0W2NZjtxjVN7sKaF-N1MWA,7774
+prodc/config.py,sha256=v2YB10QOrjfppW2vBpx_ISuyXf9myC_02-jk0hRtGlw,2801
+prodc/loader.py,sha256=UoVh0eYU_vVneDMvLAmxBkpKmwO7PvNVrBpH-nDy9rw,4669
+prodc/model.py,sha256=F7n54ldZ4trWsJDpMU2NfjGEijfGNJkamrTkFoHBexY,3884
+prodc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prodc/status.py,sha256=-7jwaq6qnGc1IijplPHr2tN5tQYqyoItpdCy3RR15pI,5436
+prodc-0.2.0.dist-info/METADATA,sha256=0XsxmdvXnSI0IhZImC4sI1Tx1-ASRXMvzbsm166J7TQ,3152
+prodc-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+prodc-0.2.0.dist-info/entry_points.txt,sha256=6oG__PQREzQvf9meznTF18lRMg5smZhl1x_yzovU2e4,41
+prodc-0.2.0.dist-info/licenses/LICENSE,sha256=6dP7w8m4xJH1IQumkEnTTCY4BJO16jnKEG-xPIj9y90,1070
+prodc-0.2.0.dist-info/RECORD,,

prodc-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

prodc-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prodc = prodc.cli:main

prodc-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Cardona
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.