prodc 0.2.0__tar.gz

prodc-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+/dist/
+/build/
+/site/
+/public/
+
+# uv / venv
+.venv/
+uv.lock.bak
+
+# Tool caches
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.moon/cache/
+
+# Editor
+.vscode/
+.idea/
+*.swp
+
+# Local session logs
+logs/
+
+# Personal, machine-specific agent overrides (AGENTS.md + CLAUDE.md are tracked)
+CLAUDE.local.md
+
+# Local agent wiring: names cabildo-issues-mcp, which is not a dependency of this
+# package. docs/issues/ IS tracked — the register is plain markdown anyone can read.
+.mcp.json
+
+# Local agent runtime state (scheduled-task locks, session scratch)
+.claude/
+
+# Local multi-agent coordination config (cabildo) — not part of the package
+.cabildo/

prodc-0.2.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes are documented here. Versioning is [SemVer](https://semver.org/).
+
+## [0.1.0] - YYYY-MM-DD
+
+Initial release.

prodc-0.2.0/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.

prodc-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,45 @@
+# 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/examples/quickstart/features/orders.feature

@@ -0,0 +1,7 @@
+Feature: Orders board
+
+  @implemented
+  Scenario: Past due orders are highlighted
+    Given an order whose due date has passed
+    When I open the orders board
+    Then the order is highlighted as past due

prodc-0.2.0/examples/quickstart/needs/jordan.yaml

@@ -0,0 +1,24 @@
+who: jordan
+label: "design partner"
+needs:
+  - id: N-1
+    text: "see which orders are past due at a glance"
+    must: true
+    sources:
+      - kind: interview
+        who: Jordan
+        date: 2026-09-20
+        quote: "I lose the past-due ones in the list"
+    proofs:
+      - "web:orders.feature#Past due orders are highlighted"
+
+  - id: N-2
+    text: "export the day's delivery run sheet"
+    sources:
+      - kind: artifact
+        locator: issues.md#N-2
+        date: 2026-09-21
+    proofs: []  # sourced HOLE: the need is evidenced, but no test proves it yet
+
+  - id: N-3
+    text: "implement a settings page"  # opinion (no source) + solution-in-disguise warning

prodc-0.2.0/examples/quickstart/prodc.toml

@@ -0,0 +1,13 @@
+# A minimal, runnable prodc project. From this directory:
+#   uv run prodc status
+# N-1 shows DELIVERED (a tagged scenario proves it), N-2 is a sourced HOLE
+# (evidence exists, no test yet), N-3 is an opinion with a solution-in-disguise warning.
+
+[prodc]
+needs = ["needs/*.yaml"]
+
+[proofs.web]
+kind = "gherkin"
+paths = ["features/*.feature"]
+delivered = ["@implemented"]
+pending = ["@pending"]

prodc-0.2.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "prodc"
+version = "0.2.0"
+description = "Product management as code: personas, flows, and features traced to evidence."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Jorge Cardona", email = "jorgeecardona@gmail.com" }]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = ["pyyaml>=6"]
+
+[project.scripts]
+prodc = "prodc.cli:main"
+
+[project.optional-dependencies]
+# docs are an *extra* (not a uv dependency-group) so Read the Docs can install them via pip
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/jorgeecardona/prodc"
+Repository = "https://gitlab.com/jorgeecardona/prodc"
+Changelog = "https://gitlab.com/jorgeecardona/prodc/-/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prodc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[dependency-groups]
+dev = ["ruff>=0.6", "pyright>=1.1.390", "pytest>=8", "types-pyyaml>=6"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["prodc"]
+
+[tool.pyright]
+include = ["src", "tests", "examples"]
+extraPaths = ["src"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"

prodc-0.2.0/src/prodc/__init__.py

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

prodc-0.2.0/src/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")