prodc 0.3.4__tar.gz → 0.3.6__tar.gz

{prodc-0.3.4 → prodc-0.3.6}/.gitignore

@@ -32,12 +32,12 @@ 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.
+# Local MCP/agent wiring — 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
+# Local multi-agent coordination state — not part of the package
 .cabildo/

{prodc-0.3.4 → prodc-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.4
+Version: 0.3.6
 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
@@ -66,6 +66,6 @@ new grammar.
 ## Layout
 
 - `src/prodc/` — the package (typed; `py.typed`).
-- `docs/issues/` — follow-ups (the `cabildo issues` convention).
+- `docs/issues/` — follow-ups, as a plain-markdown issue register.
 - `Makefile` — `format` / `lint` / `typecheck` / `test` / `check` / `build` / `docs`.
 - `AGENTS.md` — build/test/style/gotchas for coding agents.

{prodc-0.3.4 → prodc-0.3.6}/README.md

@@ -40,6 +40,6 @@ new grammar.
 ## Layout
 
 - `src/prodc/` — the package (typed; `py.typed`).
-- `docs/issues/` — follow-ups (the `cabildo issues` convention).
+- `docs/issues/` — follow-ups, as a plain-markdown issue register.
 - `Makefile` — `format` / `lint` / `typecheck` / `test` / `check` / `build` / `docs`.
 - `AGENTS.md` — build/test/style/gotchas for coding agents.

{prodc-0.3.4 → prodc-0.3.6}/pyproject.toml

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

{prodc-0.3.4 → prodc-0.3.6}/src/prodc/adapters.py

@@ -243,3 +243,74 @@ class FilesAdapter:
         if not fp.exists():
             return ProofResult(ProofState.BROKEN, False, f"no file '{payload}'")
         return ProofResult(ProofState.DELIVERED, True, "script exists")
+
+
+class AcceptAdapter:
+    """Resolves ``who@date`` to a human sign-off — a functional acceptance, not a test.
+
+    Some needs are accepted by a person, not proven by an automated test. This records
+    that as a *declared* DELIVERED (``*``), visibly distinct from a machine-checked proof;
+    it never goes BROKEN, because it is an assertion, like a tag.
+    """
+
+    def resolve(self, payload: str) -> ProofResult:
+        who, _, date = payload.partition("@")
+        detail = "accepted" + (f" by {who}" if who else "") + (f" on {date}" if date else "")
+        return ProofResult(ProofState.DELIVERED, True, detail)
+
+
+@dataclass(frozen=True)
+class SourceResult:
+    """Whether a Source.locator resolves. Verifies provenance *exists*, not that it is good."""
+
+    ok: bool
+    detail: str
+
+
+class SourceAdapter(Protocol):
+    def resolve(self, payload: str) -> SourceResult: ...
+
+
+def _slug(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+
+
+class FrontmatterAdapter:
+    """Resolves ``file#anchor`` against markdown files (e.g. docs/issues/*.md).
+
+    Confirms a heading matching the anchor exists, so a Source citing a ticket/section
+    that is absent or renamed surfaces as a dangling (BROKEN) source — the provenance-side
+    analogue of a BROKEN proof.
+    """
+
+    def __init__(self, root: Path, paths: list[str]) -> None:
+        self._root = root
+        self._paths = paths
+        self._headings: list[tuple[str, str]] | None = None  # (file name, heading text)
+
+    def _load(self) -> list[tuple[str, str]]:
+        if self._headings is not None:
+            return self._headings
+        found: list[tuple[str, str]] = []
+        heading_re = re.compile(r"^#{1,6}\s+(.*?)\s*$")
+        for pattern in self._paths:
+            for fp in sorted(self._root.glob(pattern)):
+                for line in fp.read_text(encoding="utf-8").splitlines():
+                    m = heading_re.match(line)
+                    if m:
+                        found.append((fp.name, m.group(1)))
+        self._headings = found
+        return found
+
+    def resolve(self, payload: str) -> SourceResult:
+        file_part, _, anchor = payload.partition("#")
+        if not anchor:
+            return SourceResult(False, f"no anchor in '{payload}'")
+        want = _slug(anchor)
+        for fname, heading in self._load():
+            if file_part and fname != file_part and not fname.endswith("/" + file_part):
+                continue
+            hslug = _slug(heading)
+            if hslug == want or hslug.startswith(want + "-") or anchor.lower() in heading.lower():
+                return SourceResult(True, f"{fname}: '{heading}'")
+        return SourceResult(False, f"no heading matches '{payload}'")

{prodc-0.3.4 → prodc-0.3.6}/src/prodc/cli.py

@@ -39,8 +39,15 @@ def _priority(r: NeedResult) -> int:
     }[r.state]
 
 
-# Warrant strength, strongest first: interview > artifact > internal (Torres).
-_WARRANT_ORDER = (SourceKind.INTERVIEW, SourceKind.ARTIFACT, SourceKind.INTERNAL)
+# Warrant strength, strongest first: interview > artifact > proxy > internal (Torres).
+# proxy = the author is a plausible user guessing as that user — weaker than a document,
+# stronger than a bare internal assertion.
+_WARRANT_ORDER = (
+    SourceKind.INTERVIEW,
+    SourceKind.ARTIFACT,
+    SourceKind.PROXY,
+    SourceKind.INTERNAL,
+)
 
 
 def _warrant(need: Need) -> str:
@@ -57,7 +64,7 @@ def _warrant(need: Need) -> str:
 
 def _provenance_counts(results: list[NeedResult]) -> dict[str, int]:
     """How many needs carry each warrant strength (interview/artifact/internal/opinion)."""
-    counts = {"interview": 0, "artifact": 0, "internal": 0, "opinion": 0}
+    counts = {"interview": 0, "artifact": 0, "proxy": 0, "internal": 0, "opinion": 0}
     for r in results:
         counts[_warrant(r.need).split(":", 1)[0]] += 1
     return counts
@@ -194,7 +201,7 @@ def _cmd_status(args: argparse.Namespace) -> int:
     if loaded is None:
         return 2
     cfg, needs = loaded
-    results = resolve(needs, cfg.adapters)
+    results = resolve(needs, cfg.adapters, cfg.source_adapters)
     summary = summarize(results)
     orphan_map = orphans(needs, cfg.adapters)
 
@@ -299,7 +306,7 @@ def _cmd_show(args: argparse.Namespace) -> int:
     if loaded is None:
         return 2
     cfg, needs = loaded
-    by_id = {r.need.id: r for r in resolve(needs, cfg.adapters)}
+    by_id = {r.need.id: r for r in resolve(needs, cfg.adapters, cfg.source_adapters)}
     r = by_id.get(args.need_id)
     if r is None:
         print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
@@ -330,7 +337,7 @@ def _repo_row(config_path: str) -> _RepoRow:
         needs = load_needs(cfg)
     except (ConfigError, LoaderError, OSError) as exc:
         return _RepoRow(name, 0, 0, 0, 0, 0.0, {}, error=str(exc))
-    results = resolve(needs, cfg.adapters)
+    results = resolve(needs, cfg.adapters, cfg.source_adapters)
     s = summarize(results)
     return _RepoRow(
         repo=cfg.root.name,
@@ -344,13 +351,13 @@ def _repo_row(config_path: str) -> _RepoRow:
 
 
 def _render_portfolio(rows: list[_RepoRow]) -> str:
-    out = [f"  {'repo':<18} {'cov':>4}  {'must-HOLE':>9}  {'BROKEN':>6}   prov intv/art/int/op"]
+    out = [f"  {'repo':<18} {'cov':>4}  {'must-HOLE':>9}  {'BROKEN':>6}   prov intv/art/prx/int/op"]
     for row in rows:
         if row.error is not None:
             out.append(f"  {row.repo:<18} error: {row.error}")
             continue
         p = row.provenance
-        prov = f"{p['interview']}/{p['artifact']}/{p['internal']}/{p['opinion']}"
+        prov = f"{p['interview']}/{p['artifact']}/{p['proxy']}/{p['internal']}/{p['opinion']}"
         cov = f"{round(row.coverage * 100)}%"
         out.append(
             f"  {row.repo:<18} {cov:>4}  {row.must_hole:>9}  {row.broken:>6}   {prov}"

{prodc-0.3.4 → prodc-0.3.6}/src/prodc/config.py

@@ -7,7 +7,15 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import cast
 
-from .adapters import Adapter, FilesAdapter, GherkinAdapter, PytestAdapter
+from .adapters import (
+    AcceptAdapter,
+    Adapter,
+    FilesAdapter,
+    FrontmatterAdapter,
+    GherkinAdapter,
+    PytestAdapter,
+    SourceAdapter,
+)
 
 
 class ConfigError(Exception):
@@ -34,6 +42,7 @@ class Config:
     root: Path
     need_globs: list[str]
     adapters: dict[str, Adapter] = field(default_factory=dict[str, Adapter])
+    source_adapters: dict[str, SourceAdapter] = field(default_factory=dict[str, SourceAdapter])
 
     @classmethod
     def load(cls, path: Path) -> Config:
@@ -73,8 +82,29 @@ class Config:
             elif kind == "files":
                 sub = tbl.get("root", ".")
                 adapters[name] = FilesAdapter(root=root / (sub if isinstance(sub, str) else "."))
+            elif kind == "accept":
+                adapters[name] = AcceptAdapter()
             else:
                 raise ConfigError(
-                    f"[proofs.{name}]: unknown kind {kind!r} (gherkin|pytest|files)"
+                    f"[proofs.{name}]: unknown kind {kind!r} (gherkin|pytest|files|accept)"
                 )
-        return cls(root=root, need_globs=need_globs, adapters=adapters)
+
+        source_adapters: dict[str, SourceAdapter] = {}
+        sources = _as_dict(raw.get("sources", {}), "[sources]")
+        for name, body in sources.items():
+            tbl = _as_dict(body, f"[sources.{name}]")
+            kind = tbl.get("kind")
+            if kind == "frontmatter":
+                source_adapters[name] = FrontmatterAdapter(
+                    root=root,
+                    paths=_as_str_list(tbl.get("paths", []), f"[sources.{name}].paths"),
+                )
+            else:
+                raise ConfigError(f"[sources.{name}]: unknown kind {kind!r} (frontmatter)")
+
+        return cls(
+            root=root,
+            need_globs=need_globs,
+            adapters=adapters,
+            source_adapters=source_adapters,
+        )

{prodc-0.3.4 → prodc-0.3.6}/src/prodc/model.py

@@ -17,6 +17,7 @@ class SourceKind(StrEnum):
 
     INTERVIEW = "interview"  # behavioural evidence: a named customer, a date, a verbatim quote
     ARTIFACT = "artifact"  # documentary: a ticket, doc or email locator
+    PROXY = "proxy"  # the author is a plausible user of this product, guessing as that user
     INTERNAL = "internal"  # a team member's own assertion — provenance, but not a customer's
 
 

{prodc-0.3.4 → prodc-0.3.6}/src/prodc/status.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from .adapters import Adapter, Enumerable, ProofResult
+from .adapters import Adapter, Enumerable, ProofResult, SourceAdapter
 from .model import (
     SOLUTION_VERBS,
     Need,
@@ -36,10 +36,36 @@ def _resolve_proof(locator: str, adapters: dict[str, Adapter]) -> ProofResult:
     return adapter.resolve(payload)
 
 
+def _source_warnings(need: Need, source_adapters: dict[str, SourceAdapter]) -> list[str]:
+    """Flag a Source.locator that names a configured source adapter but does not resolve.
+
+    This is a dangling (BROKEN) *source* — distinct from OPINION (no source at all). A
+    free-text locator with no matching adapter is left unchecked, not flagged.
+    """
+    out: list[str] = []
+    for s in need.sources:
+        if not s.locator:
+            continue
+        name, sep, payload = s.locator.partition(":")
+        adapter = source_adapters.get(name)
+        if not sep or adapter is None:
+            continue
+        res = adapter.resolve(payload)
+        if not res.ok:
+            out.append(f"BROKEN source '{s.locator}' ({res.detail})")
+    return out
+
+
 class Resolver:
-    def __init__(self, needs: list[Need], adapters: dict[str, Adapter]) -> None:
+    def __init__(
+        self,
+        needs: list[Need],
+        adapters: dict[str, Adapter],
+        source_adapters: dict[str, SourceAdapter] | None = None,
+    ) -> None:
         self._by_id = {n.id: n for n in needs}
         self._adapters = adapters
+        self._source_adapters = source_adapters or {}
         self._cache: dict[str, NeedResult] = {}
         self._visiting: set[str] = set()
 
@@ -55,7 +81,11 @@ class Resolver:
         self._visiting.add(need_id)
         result = self._compute(need)
         self._visiting.discard(need_id)
-        result.warnings = _text_warnings(need) + result.warnings
+        result.warnings = (
+            _text_warnings(need)
+            + _source_warnings(need, self._source_adapters)
+            + result.warnings
+        )
         self._cache[need_id] = result
         return result
 
@@ -105,9 +135,13 @@ class Resolver:
         return NeedResult(need, state, delivered, total, declared, detail, warnings)
 
 
-def resolve(needs: list[Need], adapters: dict[str, Adapter]) -> list[NeedResult]:
+def resolve(
+    needs: list[Need],
+    adapters: dict[str, Adapter],
+    source_adapters: dict[str, SourceAdapter] | None = None,
+) -> list[NeedResult]:
     """Resolve every need to a :class:`NeedResult`."""
-    return Resolver(needs, adapters).resolve_all()
+    return Resolver(needs, adapters, source_adapters).resolve_all()
 
 
 @dataclass(frozen=True)

{prodc-0.3.4 → prodc-0.3.6}/tests/test_adapters.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from prodc.adapters import FilesAdapter, PytestAdapter
+from prodc.adapters import AcceptAdapter, FilesAdapter, FrontmatterAdapter, PytestAdapter
 from prodc.model import ProofState
 
 
@@ -52,3 +52,29 @@ def test_files_adapter_existence_is_declared(tmp_path: Path) -> None:
 
 def test_files_adapter_missing_is_broken(tmp_path: Path) -> None:
     assert FilesAdapter(root=tmp_path).resolve("gone.py").state is ProofState.BROKEN
+
+
+def _frontmatter(tmp_path: Path) -> FrontmatterAdapter:
+    (tmp_path / "issues").mkdir()
+    (tmp_path / "issues" / "reg.md").write_text(
+        "# A-1 Partida doble\n\nbody\n\n## A-6 Factura electrónica\n", encoding="utf-8"
+    )
+    return FrontmatterAdapter(root=tmp_path, paths=["issues/*.md"])
+
+
+def test_frontmatter_resolves_existing_heading(tmp_path: Path) -> None:
+    a = _frontmatter(tmp_path)
+    assert a.resolve("reg.md#A-1").ok
+    assert a.resolve("reg.md#A-6").ok  # matches "## A-6 Factura electrónica"
+
+
+def test_frontmatter_dangling_anchor_or_no_anchor(tmp_path: Path) -> None:
+    a = _frontmatter(tmp_path)
+    assert not a.resolve("reg.md#A-9").ok  # no such heading
+    assert not a.resolve("reg.md#").ok  # no anchor at all
+
+
+def test_accept_adapter_is_declared_delivered() -> None:
+    r = AcceptAdapter().resolve("jane@2026-09-20")
+    assert r.state is ProofState.DELIVERED and r.declared  # a human sign-off, not a test
+    assert "accepted by jane" in r.detail and "2026-09-20" in r.detail

{prodc-0.3.4 → prodc-0.3.6}/tests/test_cli.py

@@ -177,3 +177,21 @@ def test_portfolio_bad_config_exits_2(tmp_path: Path, capsys: pytest.CaptureFixt
     code = main(["portfolio", str(tmp_path / "nope.toml")])
     capsys.readouterr()
     assert code == 2
+
+
+def test_proxy_source_kind_warrant(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    import json
+
+    (tmp_path / "needs").mkdir()
+    (tmp_path / "prodc.toml").write_text('[prodc]\nneeds = ["needs/*.yaml"]\n', encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(
+        "who: me\nneeds:\n  - id: P-1\n    text: a proxy-sourced need\n"
+        "    sources:\n      - kind: proxy\n        who: me\n        date: 2026-01-01\n",
+        encoding="utf-8",
+    )
+    toml = str(tmp_path / "prodc.toml")
+    main(["status", "--config", toml, "--json"])
+    p = json.loads(capsys.readouterr().out)
+    assert p["needs"][0]["warrant"] == "proxy"  # interview > artifact > proxy > internal
+    main(["status", "--config", toml])
+    assert "1 proxy" in capsys.readouterr().out  # provenance line counts proxy

{prodc-0.3.4 → prodc-0.3.6}/tests/test_status.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 
-from prodc.adapters import ProofResult
-from prodc.model import Need, NeedState, ProofState
+from prodc.adapters import FrontmatterAdapter, ProofResult, SourceAdapter
+from prodc.model import Need, NeedState, ProofState, Source, SourceKind
 from prodc.status import resolve
 
 
@@ -62,3 +63,20 @@ def test_solution_verb_warns() -> None:
     need = Need(id="A-1", text="implement a dashboard", proofs=())
     (r,) = resolve([need], {})
     assert any("solution in disguise" in w for w in r.warnings)
+
+
+def test_dangling_source_warns_distinct_from_opinion(tmp_path: Path) -> None:
+    (tmp_path / "issues").mkdir()
+    (tmp_path / "issues" / "reg.md").write_text("# A-1 ok\n", encoding="utf-8")
+    sources: dict[str, SourceAdapter] = {
+        "issues": FrontmatterAdapter(root=tmp_path, paths=["issues/*.md"])
+    }
+    good = Need(id="N-1", text="t",
+                sources=(Source(kind=SourceKind.ARTIFACT, locator="issues:reg.md#A-1"),))
+    bad = Need(id="N-2", text="t",
+               sources=(Source(kind=SourceKind.ARTIFACT, locator="issues:reg.md#NOPE"),))
+    results = {r.need.id: r for r in resolve([good, bad], {}, sources)}
+    assert not any("BROKEN source" in w for w in results["N-1"].warnings)
+    assert any("BROKEN source" in w for w in results["N-2"].warnings)
+    # both are sourced, so neither is an opinion — BROKEN-source is a distinct signal
+    assert not results["N-2"].need.is_opinion