prodc 0.3.7__tar.gz → 0.3.9__tar.gz

{prodc-0.3.7 → prodc-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.7
+Version: 0.3.9
 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
@@ -44,8 +44,34 @@ The lineage is Toulmin's argument model (claim + grounds + warrant): a feature i
 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.
+## What it's for
+
+prodc does not replace the human conversation with a client — it is scaffolding around it.
+Going in, the board already shows what is still unknown for that client: needs with no
+evidence (opinions) and needs with no proof (HOLEs), so the meeting is spent closing real
+gaps instead of re-deriving them. Coming out, what was learned is captured as evidence on
+the need, so the next decision is planned from the repo rather than from memory. The board
+answers "where are we" and "what's blocking" between meetings, without a standup.
+
+## Prior art
+
+prodc draws on, and tries to credit, several existing lines of work:
+
+- **Continuous discovery / opportunity framing** — Teresa Torres (opportunity = need; the
+  interview > artifact > internal evidence ladder; "solutions in disguise").
+- **The argument/assurance model** — Toulmin (claim · grounds · warrant) and the safety-case
+  / GSN tradition it informs.
+- **Spec-driven development** — product/requirements modelled as plain JSON/YAML in git
+  (the ThoughtWorks / Fowler SDD writing).
+- **Structured requirements** — EARS (Easy Approach to Requirements Syntax), the NASA
+  requirement-writing guidance, and the SysML lineage.
+- **Requirements-as-code tooling** — Doorstop and StrictDoc (plain-text, git-tracked, linked
+  IDs), which prodc follows in form but points at product artifacts rather than "shall"
+  statements.
+
+> Status: v0.3, on PyPI (`pip install prodc`). The model (Need · Source · Proof), the proof
+> and source adapters, and the status / show / diff / portfolio commands are in; see
+> `docs/issues/` for what's still open.
 
 ## Install
 

{prodc-0.3.7 → prodc-0.3.9}/README.md

@@ -18,8 +18,34 @@ The lineage is Toulmin's argument model (claim + grounds + warrant): a feature i
 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.
+## What it's for
+
+prodc does not replace the human conversation with a client — it is scaffolding around it.
+Going in, the board already shows what is still unknown for that client: needs with no
+evidence (opinions) and needs with no proof (HOLEs), so the meeting is spent closing real
+gaps instead of re-deriving them. Coming out, what was learned is captured as evidence on
+the need, so the next decision is planned from the repo rather than from memory. The board
+answers "where are we" and "what's blocking" between meetings, without a standup.
+
+## Prior art
+
+prodc draws on, and tries to credit, several existing lines of work:
+
+- **Continuous discovery / opportunity framing** — Teresa Torres (opportunity = need; the
+  interview > artifact > internal evidence ladder; "solutions in disguise").
+- **The argument/assurance model** — Toulmin (claim · grounds · warrant) and the safety-case
+  / GSN tradition it informs.
+- **Spec-driven development** — product/requirements modelled as plain JSON/YAML in git
+  (the ThoughtWorks / Fowler SDD writing).
+- **Structured requirements** — EARS (Easy Approach to Requirements Syntax), the NASA
+  requirement-writing guidance, and the SysML lineage.
+- **Requirements-as-code tooling** — Doorstop and StrictDoc (plain-text, git-tracked, linked
+  IDs), which prodc follows in form but points at product artifacts rather than "shall"
+  statements.
+
+> Status: v0.3, on PyPI (`pip install prodc`). The model (Need · Source · Proof), the proof
+> and source adapters, and the status / show / diff / portfolio commands are in; see
+> `docs/issues/` for what's still open.
 
 ## Install
 

{prodc-0.3.7 → prodc-0.3.9}/pyproject.toml

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

{prodc-0.3.7 → prodc-0.3.9}/src/prodc/adapters.py

@@ -274,6 +274,89 @@ class AcceptAdapter:
         return ProofResult(ProofState.DELIVERED, True, detail)
 
 
+class CoverageAdapter:
+    """Resolves a category path against a catalog of existing categories (one per line).
+
+    DELIVERED when a category matches (already covered — point them at it); PENDING when
+    nothing matches (declared, not yet covered — an honest gap, not a build failure).
+    """
+
+    def __init__(self, root: Path, catalog: str) -> None:
+        self._path = root / catalog
+        self._cats: set[str] | None = None
+
+    def _load(self) -> set[str]:
+        if self._cats is None:
+            out: set[str] = set()
+            if self._path.exists():
+                for line in self._path.read_text(encoding="utf-8").splitlines():
+                    s = line.strip()
+                    if s and not s.startswith("#"):
+                        out.add(s)
+            self._cats = out
+        return self._cats
+
+    def resolve(self, payload: str) -> ProofResult:
+        if payload in self._load():
+            return ProofResult(ProofState.DELIVERED, True, f"covered by '{payload}'")
+        return ProofResult(ProofState.PENDING, True, f"no category matches '{payload}'")
+
+
+class FieldAdapter:
+    """Resolves a field name against an upstream schema/sample JSON.
+
+    Schema: ``{"surfaced": [...], "received": [...]}``. DELIVERED if the field is surfaced;
+    PENDING otherwise, with a distinct detail for 'received but not surfaced' vs 'not
+    received upstream' — a different fix. Never a hard failure.
+    """
+
+    def __init__(self, root: Path, schema: str) -> None:
+        self._path = root / schema
+        self._data: tuple[set[str], set[str]] | None = None
+
+    def _load(self) -> tuple[set[str], set[str]]:
+        if self._data is None:
+            surfaced: set[str] = set()
+            received: set[str] = set()
+            if self._path.exists():
+                raw: object = json.loads(self._path.read_text(encoding="utf-8"))
+                if isinstance(raw, dict):
+                    d = cast("dict[str, object]", raw)
+                    s, r = d.get("surfaced"), d.get("received")
+                    if isinstance(s, list):
+                        surfaced = {x for x in cast("list[object]", s) if isinstance(x, str)}
+                    if isinstance(r, list):
+                        received = {x for x in cast("list[object]", r) if isinstance(x, str)}
+            self._data = (surfaced, received)
+        return self._data
+
+    def resolve(self, payload: str) -> ProofResult:
+        surfaced, received = self._load()
+        if payload in surfaced:
+            return ProofResult(ProofState.DELIVERED, True, f"'{payload}' present and surfaced")
+        if payload in received:
+            return ProofResult(ProofState.PENDING, True, f"'{payload}' received but not surfaced")
+        return ProofResult(ProofState.PENDING, True, f"'{payload}' not received upstream")
+
+
+class PrototypeAdapter:
+    """Resolves ``ref@who@date`` to a prototype validated with users in discovery.
+
+    For perception/experience needs with no pass/fail test: a prototype shown to users in
+    an interview is real evidence of the need and the chosen direction. A *declared*
+    DELIVERED (``*``), distinct from a shipped-feature test and from a human sign-off
+    (accept) — this validates the need/direction, not the implementation.
+    """
+
+    def resolve(self, payload: str) -> ProofResult:
+        ref, _, rest = payload.partition("@")
+        who, _, date = rest.partition("@")
+        detail = "prototype " + (ref or "?")
+        detail += f" shown to {who}" if who else ""
+        detail += f" on {date}" if date else ""
+        return ProofResult(ProofState.DELIVERED, True, detail)
+
+
 class External:
     """Wraps a proof adapter that resolves against a sibling repo checked out at ``repo``.
 

{prodc-0.3.7 → prodc-0.3.9}/src/prodc/cli.py

@@ -13,6 +13,7 @@ import shutil
 import sys
 from dataclasses import asdict, dataclass
 from pathlib import Path
+from typing import cast
 
 from . import __version__
 from .config import Config, ConfigError
@@ -380,6 +381,51 @@ def _cmd_portfolio(args: argparse.Namespace) -> int:
     return 2 if any(r.error is not None for r in rows) else 0
 
 
+def _cmd_diff(args: argparse.Namespace) -> int:
+    """Diff the current board against a prior `status --json` snapshot."""
+    loaded = _load_or_report(args)
+    if loaded is None:
+        return 2
+    cfg, needs = loaded
+    current = {r.need.id: r.state.value for r in resolve(needs, cfg.adapters, cfg.source_adapters)}
+
+    snap = Path(args.snapshot)
+    try:
+        payload: object = json.loads(snap.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        print(f"prodc: cannot read snapshot {snap}: {exc}", file=sys.stderr)
+        return 2
+    raw_needs = cast("dict[str, object]", payload).get("needs") if isinstance(payload, dict) else None
+    old: dict[str, str] = {}
+    for n in cast("list[object]", raw_needs) if isinstance(raw_needs, list) else []:
+        if isinstance(n, dict):
+            entry = cast("dict[str, object]", n)
+            nid, st = entry.get("id"), entry.get("state")
+            if isinstance(nid, str) and isinstance(st, str):
+                old[nid] = st
+
+    new = {i: current[i] for i in sorted(current.keys() - old.keys())}
+    removed = sorted(old.keys() - current.keys())
+    changed = {
+        i: [old[i], current[i]] for i in sorted(old.keys() & current.keys()) if old[i] != current[i]
+    }
+    if args.json:
+        print(json.dumps({"new": new, "removed": removed, "changed": changed}, indent=2))
+        return 0
+    if not (new or removed or changed):
+        print("no changes since snapshot")
+        return 0
+    out: list[str] = []
+    for i, st in new.items():
+        out.append(f"  new      {i:<10} ({st})")
+    for i in removed:
+        out.append(f"  removed  {i}")
+    for i, (was, now) in changed.items():
+        out.append(f"  changed  {i:<10} {was} → {now}")
+    print("\n".join(out))
+    return 0
+
+
 def _git_rev(root: Path) -> str | None:
     head = root / ".git" / "HEAD"
     try:
@@ -437,6 +483,12 @@ def main(argv: list[str] | None = None) -> int:
     pf.add_argument("--json", action="store_true", help="machine-readable output")
     pf.set_defaults(func=_cmd_portfolio)
 
+    df = sub.add_parser("diff", help="diff the current board against a prior status --json snapshot")
+    df.add_argument("snapshot", help="path to a saved `prodc status --json` file")
+    df.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    df.add_argument("--json", action="store_true", help="machine-readable output")
+    df.set_defaults(func=_cmd_diff)
+
     args = parser.parse_args(argv)
     return int(args.func(args))
 

{prodc-0.3.7 → prodc-0.3.9}/src/prodc/config.py

@@ -10,10 +10,13 @@ from typing import cast
 from .adapters import (
     AcceptAdapter,
     Adapter,
+    CoverageAdapter,
     External,
+    FieldAdapter,
     FilesAdapter,
     FrontmatterAdapter,
     GherkinAdapter,
+    PrototypeAdapter,
     PytestAdapter,
     SourceAdapter,
 )
@@ -89,9 +92,20 @@ class Config:
                 inner = FilesAdapter(root=proof_root / (sub if isinstance(sub, str) else "."))
             elif kind == "accept":
                 inner = AcceptAdapter()
+            elif kind == "prototype":
+                inner = PrototypeAdapter()
+            elif kind == "coverage":
+                cat = tbl.get("catalog", "")
+                inner = CoverageAdapter(
+                    root=proof_root, catalog=cat if isinstance(cat, str) else ""
+                )
+            elif kind == "field":
+                sch = tbl.get("schema", "")
+                inner = FieldAdapter(root=proof_root, schema=sch if isinstance(sch, str) else "")
             else:
                 raise ConfigError(
-                    f"[proofs.{name}]: unknown kind {kind!r} (gherkin|pytest|files|accept)"
+                    f"[proofs.{name}]: unknown kind {kind!r} "
+                    "(gherkin|pytest|files|accept|prototype|coverage|field)"
                 )
             adapters[name] = (
                 External(inner, root / repo_field) if isinstance(repo_field, str) else inner

{prodc-0.3.7 → prodc-0.3.9}/tests/test_adapters.py

@@ -6,9 +6,12 @@ from pathlib import Path
 
 from prodc.adapters import (
     AcceptAdapter,
+    CoverageAdapter,
     External,
+    FieldAdapter,
     FilesAdapter,
     FrontmatterAdapter,
+    PrototypeAdapter,
     PytestAdapter,
 )
 from prodc.model import ProofState
@@ -92,6 +95,32 @@ def test_external_unresolved_when_sibling_absent(tmp_path: Path) -> None:
     assert r.state is ProofState.UNRESOLVED and not r.declared
 
 
+def test_prototype_adapter_declared_delivered() -> None:
+    r = PrototypeAdapter().resolve("fig-12@users@2026-09-20")
+    assert r.state is ProofState.DELIVERED and r.declared
+    assert "prototype fig-12" in r.detail and "users" in r.detail
+
+
+def test_coverage_adapter(tmp_path: Path) -> None:
+    (tmp_path / "catalog.txt").write_text("billing/invoices\n# a comment\nroasting/queue\n",
+                                           encoding="utf-8")
+    a = CoverageAdapter(root=tmp_path, catalog="catalog.txt")
+    assert a.resolve("billing/invoices").state is ProofState.DELIVERED
+    assert a.resolve("shipping/labels").state is ProofState.PENDING  # not yet covered
+
+
+def test_field_adapter(tmp_path: Path) -> None:
+    (tmp_path / "schema.json").write_text(
+        '{"surfaced": ["total"], "received": ["total", "tax_id"]}', encoding="utf-8"
+    )
+    a = FieldAdapter(root=tmp_path, schema="schema.json")
+    assert a.resolve("total").state is ProofState.DELIVERED
+    r = a.resolve("tax_id")
+    assert r.state is ProofState.PENDING and "received but not surfaced" in r.detail
+    r2 = a.resolve("missing")
+    assert r2.state is ProofState.PENDING and "not received upstream" in r2.detail
+
+
 def test_external_reads_sibling_and_records_rev(tmp_path: Path) -> None:
     sib = tmp_path / "sib"
     sib.mkdir()

{prodc-0.3.7 → prodc-0.3.9}/tests/test_cli.py

@@ -179,6 +179,30 @@ def test_portfolio_bad_config_exits_2(tmp_path: Path, capsys: pytest.CaptureFixt
     assert code == 2
 
 
+def test_diff_no_changes(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    toml = str(_project(tmp_path))
+    main(["status", "--config", toml, "--json"])
+    snap = tmp_path / "snap.json"
+    snap.write_text(capsys.readouterr().out, encoding="utf-8")
+    main(["diff", str(snap), "--config", toml])
+    assert "no changes" in capsys.readouterr().out
+
+
+def test_diff_reports_new_need(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    toml = str(_project(tmp_path))
+    main(["status", "--config", toml, "--json"])
+    snap = tmp_path / "snap.json"
+    snap.write_text(capsys.readouterr().out, encoding="utf-8")
+    # add a brand-new need, then diff against the snapshot
+    (tmp_path / "needs" / "a.yaml").write_text(
+        _NEEDS + "  - id: X-9\n    text: a newly added need\n", encoding="utf-8"
+    )
+    code = main(["diff", str(snap), "--config", toml])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "new" in out and "X-9" in out
+
+
 def test_proxy_source_kind_warrant(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
     import json