prodc 0.3.66__tar.gz → 0.3.72__tar.gz

{prodc-0.3.66 → prodc-0.3.72}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.66
+Version: 0.3.72
 Summary: Product management as code: roles, flows, and features traced to evidence.
 Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
 Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc

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

@@ -0,0 +1,40 @@
+who: jordan
+label: "design partner"
+needs:
+  - id: N-1
+    text: "see which orders are past due at a glance"
+    must: true
+    sources:
+      - kind: primary
+        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: secondary
+        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
+
+  # A product need is a hypothesis, same as a research question. Stating the `claim` (the warrant
+  # the bet would establish) silences the EARS/solution-verb lint — the honest act, not a mode.
+  # The experiment shipped and settled the question NO: DELIVERED + answer: no. It stays on the
+  # board and counts as a result — unlike `withdrawn`, which would hide that something was learned.
+  - id: N-4
+    text: "pin the daily summary to the top of the dashboard"
+    claim: "pinning the summary lifts next-day return visits"
+    sources:
+      - kind: primary
+        who: Jordan
+        date: 2026-09-22
+        quote: "I never scroll back up to the summary"
+    proofs:
+      - "ship:jordan@2026-10-05"  # the A/B experiment ran and concluded
+    answer: no  # return visits did not move — the bet is settled, and the answer is no

{prodc-0.3.66 → prodc-0.3.72}/examples/quickstart/prodc.toml

@@ -1,7 +1,8 @@
 # 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.
+# (evidence exists, no test yet), N-3 is an opinion with a solution-in-disguise warning,
+# N-4 is a shipped hypothesis that settled NO (DELIVERED + answer: no — a result, not a gap).
 
 [prodc]
 needs = ["needs/*.yaml"]
@@ -11,3 +12,6 @@ kind = "gherkin"
 paths = ["features/*.feature"]
 delivered = ["@implemented"]
 pending = ["@pending"]
+
+[proofs.ship]
+kind = "accept"  # a human records that an experiment ran and concluded (declared)

{prodc-0.3.66 → prodc-0.3.72}/pyproject.toml

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

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/adapters.py

@@ -40,6 +40,23 @@ def _steps_passed(steps: list[object]) -> bool:
     return True
 
 
+def _as_score(val: object) -> float | None:
+    """A numeric eval score from a results value: a bare number, or ``{"score": N}``.
+
+    ``bool`` is a subclass of ``int`` but is a pass/fail, not a score, so it is rejected — a
+    boolean result belongs to :class:`OutcomeAdapter`, not the gate.
+    """
+    if isinstance(val, bool):
+        return None
+    if isinstance(val, (int, float)):
+        return float(val)
+    if isinstance(val, dict):
+        inner = cast("dict[str, object]", val).get("score")
+        if isinstance(inner, (int, float)) and not isinstance(inner, bool):
+            return float(inner)
+    return None
+
+
 def _git_head(repo: Path) -> str | None:
     """Short git rev of a checked-out repo, read from .git/HEAD (no git binary needed)."""
     head = repo / ".git" / "HEAD"
@@ -486,6 +503,79 @@ class OutcomeAdapter:
         return ProofResult(ProofState.PENDING, False, f"outcome '{payload}' recorded failing")
 
 
+#: Comparators an evalgate locator may use, strongest-looking first so ``>=``/``<=`` match
+#: before the bare ``>``/``<`` when scanning the locator.
+_EVAL_OPS: dict[str, Callable[[float, float], bool]] = {
+    ">=": lambda s, t: s >= t,
+    "<=": lambda s, t: s <= t,
+    ">": lambda s, t: s > t,
+    "<": lambda s, t: s < t,
+}
+_EVAL_RE = re.compile(r"^(?P<key>.+?)(?P<op><=|>=|<|>)(?P<thr>[^<>=]+)$")
+
+
+class EvalGateAdapter:
+    """Resolves ``metric>=threshold`` against a recorded eval score (#75).
+
+    A scored sibling of :class:`OutcomeAdapter`: where that reads a pass/fail bool, this reads a
+    numeric score and gates it against a threshold carried in the locator (``accuracy>=0.9``), so
+    one adapter serves many metrics and cutoffs (``>=``, ``<=``, ``>``, ``<`` — ``<=`` for a loss
+    you want below a bound). The score is produced by an eval harness *outside* prodc and recorded
+    in a JSON file (``{"accuracy": {"score": 0.82}}`` or the bare ``{"accuracy": 0.82}``); prodc
+    only reads it — records-only, never runs the eval.
+
+    DELIVERED when the comparison holds; PENDING when the score is recorded but does not meet the
+    gate, or the metric is absent from a present file (recorded-below and not-yet-recorded are both
+    "not green", as in :class:`OutcomeAdapter`); BROKEN when the results file is absent or the
+    locator is malformed. The score, comparator and threshold go in the detail so the board shows
+    how far off it is.
+    """
+
+    def __init__(self, root: Path, results: str) -> None:
+        self._path = root / results
+        self._data: dict[str, float] | None = None
+        self._loaded = False
+
+    def _load(self) -> dict[str, float] | None:
+        if not self._loaded:
+            self._loaded = True
+            if self._path.exists():
+                out: dict[str, float] = {}
+                raw: object = json.loads(self._path.read_text(encoding="utf-8"))
+                if isinstance(raw, dict):
+                    for key, val in cast("dict[str, object]", raw).items():
+                        score = _as_score(val)
+                        if score is not None:
+                            out[key] = score
+                self._data = out
+        return self._data
+
+    def resolve(self, payload: str) -> ProofResult:
+        m = _EVAL_RE.match(payload.strip())
+        if not m:
+            return ProofResult(
+                ProofState.BROKEN, False, f"malformed evalgate '{payload}' (want metric>=threshold)"
+            )
+        key = m.group("key").strip()
+        op = m.group("op")
+        try:
+            threshold = float(m.group("thr").strip())
+        except ValueError:
+            return ProofResult(
+                ProofState.BROKEN, False, f"evalgate threshold not a number '{payload}'"
+            )
+        data = self._load()
+        if data is None:
+            return ProofResult(ProofState.BROKEN, False, f"no results file '{self._path.name}'")
+        if key not in data:
+            return ProofResult(ProofState.PENDING, False, f"metric '{key}' not in results")
+        score = data[key]
+        passed = _EVAL_OPS[op](score, threshold)
+        verdict = "pass" if passed else "below gate"
+        detail = f"{key} {score:g} {op} {threshold:g} ({verdict})"
+        return ProofResult(ProofState.DELIVERED if passed else ProofState.PENDING, False, detail)
+
+
 class CommandProof:
     """Resolves a locator by running a user-supplied command — a proof hook (#70).
 
@@ -549,6 +639,27 @@ class PrototypeAdapter:
         return ProofResult(ProofState.DELIVERED, True, detail)
 
 
+class CitationAdapter:
+    """Resolves ``ref@author@year`` to a cited published result — a declared DELIVERED (#75).
+
+    A research question can be settled by citing a result a human vouches for and prodc cannot
+    check (a published paper, a textbook theorem). Modelled on :class:`PrototypeAdapter`: a
+    *declared* DELIVERED (``*``), never BROKEN, because it is an assertion, like a tag. Kept
+    distinct from ``accept`` on purpose — ``accept`` records *who signed off*; a citation records
+    *what external result settles it*, and ``ref`` (the thing a reader follows to check the claim)
+    is the load-bearing payload ``accept`` has no slot for: ``accept:Smith2019@jorge@...`` would
+    read as "jorge accepted it", hiding that the truth is "Smith 2019 shows it".
+    """
+
+    def resolve(self, payload: str) -> ProofResult:
+        ref, _, rest = payload.partition("@")
+        author, _, year = rest.partition("@")
+        detail = "cites " + (ref or "?")
+        detail += f" by {author}" if author else ""
+        detail += f" ({year})" if year 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.66 → prodc-0.3.72}/src/prodc/board.py

@@ -97,6 +97,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
             "goal": need.goal,
             "release": need.release,
             "claim": need.claim,
+            "answer": need.answer.value if need.answer else None,
             "withdrawn": (
                 {"reason": need.withdrawn.reason, "date": need.withdrawn.date}
                 if need.withdrawn
@@ -143,6 +144,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
         "release": need.release,
         "product": need.product,
         "draft": need.draft,
+        "answer": need.answer.value if need.answer else None,
         "withdrawn": (
             {"reason": need.withdrawn.reason, "date": need.withdrawn.date}
             if need.withdrawn

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/cli/render.py

@@ -273,6 +273,8 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
         f"  grounds: {_LABEL[r.state]}{nm}    warrant: {_warrant(need)}",
         f"  shape: {ears_shape(need.text).value}",
     ]
+    if need.answer:
+        lines.append(f"  answer: {need.answer.value}")
     if need.withdrawn:
         lines.append(f"  withdrawn: {need.withdrawn.reason} ({need.withdrawn.date})")
     if need.description:

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/config.py

@@ -10,9 +10,11 @@ from typing import cast
 from .adapters import (
     AcceptAdapter,
     Adapter,
+    CitationAdapter,
     CommandProof,
     CommandSource,
     CoverageAdapter,
+    EvalGateAdapter,
     External,
     FieldAdapter,
     FilesAdapter,
@@ -190,6 +192,8 @@ class Config:
                 inner = AcceptAdapter()
             elif kind == "prototype":
                 inner = PrototypeAdapter()
+            elif kind == "citation":
+                inner = CitationAdapter()
             elif kind == "coverage":
                 cat = tbl.get("catalog", "")
                 inner = CoverageAdapter(
@@ -202,13 +206,17 @@ class Config:
                 if not results_s:
                     raise ConfigError(f"[proofs.{name}]: external needs results = <json file>")
                 inner = OutcomeAdapter(root=proof_root, results=results_s)
+            elif kind == "evalgate":
+                if not results_s:
+                    raise ConfigError(f"[proofs.{name}]: evalgate needs results = <json file>")
+                inner = EvalGateAdapter(root=proof_root, results=results_s)
             elif kind == "command":
                 command, timeout = _hook_command(tbl, f"[proofs.{name}]")
                 inner = CommandProof(root=proof_root, command=command, timeout=timeout)
             else:
                 raise ConfigError(
                     f"[proofs.{name}]: unknown kind {kind!r} "
-                    "(gherkin|pytest|files|accept|prototype|coverage|field|external|command)"
+                    "(gherkin|pytest|files|accept|prototype|citation|coverage|field|external|evalgate|command)"
                 )
             adapters[name] = (
                 External(inner, root / repo_field) if isinstance(repo_field, str) else inner

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/loader.py

@@ -17,6 +17,7 @@ import yaml
 
 from .config import Config
 from .model import (
+    Answer,
     ArgKind,
     ArgNode,
     Attestation,
@@ -105,6 +106,29 @@ def _attestation(raw: object, where: str) -> Attestation | None:
     )
 
 
+def _answer(raw: object, where: str) -> Answer | None:
+    """Parse ``answer: yes|no|inconclusive`` into an :class:`Answer`, validated like other enums.
+
+    The direction a settled research question resolved; absent on a product need. Same
+    ``Enum(name) except ValueError`` pattern as ``SourceKind``/``ArgKind`` so an unknown value is
+    a :class:`LoaderError` the author owns, not silent junk.
+
+    YAML 1.1 reads a bare ``yes``/``no`` as a boolean, so ``answer: no`` arrives as ``False`` —
+    coerced back to the string here, the same way ``_opt_str`` accepts a bare ``date:`` that
+    parsed as a date. ``inconclusive`` is a plain string and needs no coercion.
+    """
+    if raw is None:
+        return None
+    if isinstance(raw, bool):
+        raw = "yes" if raw else "no"
+    name = _as_str(raw, where)
+    try:
+        return Answer(name)
+    except ValueError:
+        answers = "|".join(a.value for a in Answer)
+        raise LoaderError(f"{where}: unknown answer {name!r} ({answers})") from None
+
+
 def _withdrawal(raw: object, where: str) -> Withdrawal | None:
     """Parse ``withdrawn: {reason, date}`` into a :class:`Withdrawal` (#74).
 
@@ -178,6 +202,7 @@ def _need(
     product = _as_bool(tbl["product"], f"{where}.product") if "product" in tbl else True
     draft = _as_bool(tbl["draft"], f"{where}.draft") if "draft" in tbl else False
     withdrawn = _withdrawal(tbl.get("withdrawn"), f"{where}.withdrawn")
+    answer = _answer(tbl.get("answer"), f"{where}.answer")
 
     sources = tuple(
         _source(s, f"{where}.sources[{i}]")
@@ -236,6 +261,7 @@ def _need(
         importance_set_at=importance_set_at,
         draft=draft,
         withdrawn=withdrawn,
+        answer=answer,
     )
 
 

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/model.py

@@ -48,6 +48,26 @@ class NeedState(StrEnum):
     UNRESOLVED = "unresolved"  # a proof's source could not be read (e.g. sibling repo absent)
 
 
+class Answer(StrEnum):
+    """Which way a settled question resolved — the research board's direction axis.
+
+    A product need has one axis: is the outcome achieved? A research question has two: is it
+    *settled* (DELIVERED, the proof resolved green) and, if so, *which way*. DELIVERED means
+    settled; ``answer`` records the direction. A disproven hypothesis is therefore a settled
+    result that still counts toward coverage — DELIVERED with ``answer: no`` — not a gap.
+
+    Direction is always authored, never computed: an adapter can only map a proof to
+    delivered/pending/broken/unresolved, so no adapter can emit a settled-NO. The act of
+    concluding "this is the answer, and it is no" is the author's decision, so ``answer`` lives
+    on the :class:`Need` (authored lifecycle), not on a proof or need result (computed). A product
+    board never sets it and behaves exactly as before.
+    """
+
+    YES = "yes"  # the question settled affirmatively
+    NO = "no"  # the question settled negatively — a result, not a gap (e.g. a disproven hypothesis)
+    INCONCLUSIVE = "inconclusive"  # settled that the evidence cannot decide it either way
+
+
 @dataclass(frozen=True)
 class Source:
     """Where a need came from. Absence of any Source makes the need an opinion."""
@@ -179,6 +199,9 @@ class Need:
     product: bool = True  # False = infra/NFR/internal, excluded from product coverage (#48)
     draft: bool = False  # True = staged, not yet counted on the board until promoted (#60)
     withdrawn: Withdrawal | None = None  # a decision against this need — off the board (#74)
+    answer: Answer | None = (
+        None  # which way a settled need resolved (yes/no/inconclusive); None=open-ended
+    )
     not_duplicate_of: tuple[str, ...] = ()  # ids this need is confirmed NOT a duplicate of (#55)
     not_variant_of: tuple[str, ...] = ()  # ids this need is confirmed NOT a shared variant of (#56)
 

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/status.py

@@ -15,6 +15,7 @@ from .adapters import Adapter, Enumerable, Inventoried, ProofResult, SourceAdapt
 from .dedup import similarity
 from .model import (
     SOLUTION_VERBS,
+    Answer,
     ArgKind,
     ArgNode,
     AttestationKind,
@@ -29,14 +30,27 @@ from .model import (
     ears_warnings,
 )
 
+#: Reserved proof-adapter name for a need→need edge (#research-board step 2): a proof whose
+#: payload is another need id. Resolved by the :class:`Resolver` itself, not a config adapter,
+#: so it never appears in ``[proofs.*]``; a ``[proofs.need]`` block would be shadowed by this.
+_NEEDREF = "need"
+
 
 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}')")
-    else:
-        out.extend(ears_warnings(need.text))  # EARS shape check (redundant on solution verbs)
+    # The outcome-shape lint (EARS + solution-verb) fires only until the author states the
+    # warrant. A need with `claim` set has already articulated the proposition the lint was
+    # prodding toward — "what delivering this establishes" — so it is silenced. This is what
+    # unifies a product board and a research board without a mode: "When a roaster opens the
+    # queue, she can see today's orders" and "π is irrational" are the same claim-under-uncertainty
+    # at different altitudes; EARS is just one falsifiable-claim grammar, a stated `claim` another.
+    if need.claim is None:
+        first = need.text.strip().split(" ", 1)[0].lower().rstrip(":")
+        if first in SOLUTION_VERBS:
+            out.append(f"text may be a solution in disguise (starts with '{first}')")
+        else:
+            out.extend(ears_warnings(need.text))  # EARS shape check (redundant on solution verbs)
+    # Source hygiene is universal (it is about evidence, not phrasing) — always run it.
     for src in need.sources:
         out.extend(src.warnings())
     return out
@@ -110,6 +124,23 @@ def _warrant_warnings(need: Need, result: NeedResult) -> list[str]:
     return []
 
 
+def _answer_warnings(need: Need, result: NeedResult) -> list[str]:
+    """Flag an ``answer`` authored on a question that is not settled (research board).
+
+    DELIVERED means settled; ``answer`` records which way it settled. An answer declared while
+    the state is anything but DELIVERED is a claim the proofs do not yet support — surface it.
+    Conservative by design: the check never cross-examines the proof detail against the
+    direction (a ``command:lean/¬P`` counterexample legitimately pairs DELIVERED with ``no``),
+    so only settledness is checked here, not which way.
+    """
+    if need.answer is not None and result.state is not NeedState.DELIVERED:
+        return [
+            f"answer '{need.answer.value}' declared on an unsettled question "
+            f"(state {result.state.value})"
+        ]
+    return []
+
+
 class Resolver:
     def __init__(
         self,
@@ -139,6 +170,7 @@ class Resolver:
             _text_warnings(need)
             + _source_warnings(need, self._source_adapters)
             + _warrant_warnings(need, result)
+            + _answer_warnings(need, result)
             + result.warnings
         )
         self._cache[need_id] = result
@@ -149,10 +181,73 @@ class Resolver:
             return self._aggregate_children(need)
         return self._resolve_leaf(need)
 
+    def _resolve_one(self, locator: str) -> ProofResult:
+        """Resolve one leaf proof locator, routing ``need:`` to the needref edge.
+
+        Every other adapter reads a repo; a needref reads another need's resolution, which only
+        the resolver can do — so it is dispatched here, not via :func:`_resolve_proof`.
+        """
+        name, sep, payload = locator.partition(":")
+        if sep and name == _NEEDREF:
+            return self._resolve_needref(payload)
+        return _resolve_proof(locator, self._adapters)
+
+    def _resolve_needref(self, payload: str) -> ProofResult:
+        """Resolve ``need:<id>`` (or ``need:<id>@<answer>``) against another need (#research step 2).
+
+        A research question can depend on a peer: "B cannot be posed until A is settled." That
+        edge is itself a proof — B delivers iff A is settled — so it rides the ``proofs`` tuple
+        with no new field, and the resolver's own cycle detection and memoization cover A→B→A for
+        free (a back-edge hits the ``_visiting`` guard and returns BROKEN). ``need:A`` resolves on
+        A's *settledness* (DELIVERED); the optional ``need:A@yes`` form additionally requires A's
+        authored :attr:`~prodc.model.Need.answer` to match. B never inherits A's answer — the
+        dependency only requires A settled, optionally in a given direction.
+        """
+        ref_id, sep, direction = payload.partition("@")
+        ref_id = ref_id.strip()
+        if ref_id not in self._by_id:
+            return ProofResult(ProofState.BROKEN, False, f"need '{ref_id}' is not a known need id")
+        want: Answer | None = None
+        if sep:
+            try:
+                want = Answer(direction.strip())
+            except ValueError:
+                answers = "|".join(a.value for a in Answer)
+                return ProofResult(
+                    ProofState.BROKEN, False, f"unknown answer '{direction}' ({answers})"
+                )
+        cr = self.resolve(ref_id)  # cycle-safe via the _visiting guard in resolve()
+        if cr.state is NeedState.BROKEN:
+            return ProofResult(ProofState.BROKEN, False, f"need '{ref_id}' unresolved (broken)")
+        if cr.state is NeedState.UNRESOLVED:
+            return ProofResult(ProofState.UNRESOLVED, False, f"need '{ref_id}' could not be read")
+        if cr.state is not NeedState.DELIVERED:
+            return ProofResult(
+                ProofState.PENDING, False, f"need '{ref_id}' not settled ({cr.state.value})"
+            )
+        if want is None:
+            return ProofResult(ProofState.DELIVERED, cr.declared, f"need '{ref_id}' settled")
+        answer = self._by_id[ref_id].answer
+        if answer is None:
+            return ProofResult(
+                ProofState.PENDING,
+                False,
+                f"need '{ref_id}' settled, no answer recorded, awaiting '{want.value}'",
+            )
+        if answer is want:
+            return ProofResult(
+                ProofState.DELIVERED, cr.declared, f"need '{ref_id}' settled: {answer.value}"
+            )
+        return ProofResult(
+            ProofState.PENDING,
+            False,
+            f"need '{ref_id}' settled {answer.value}, awaiting '{want.value}'",
+        )
+
     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]
+        results = [self._resolve_one(p) 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)

{prodc-0.3.66 → prodc-0.3.72}/src/prodc/writer.py

@@ -167,6 +167,24 @@ def _item_id(lines: list[str], start: int, item_indent: int) -> str | None:
     return None
 
 
+def _normalize_answer(doc: dict[str, object]) -> None:
+    """Rewrite a need's ``answer`` back to its yes/no string before re-dump.
+
+    YAML 1.1 reads a bare ``answer: no`` as the boolean ``False``, so the raw dict carries a
+    bool; dumping it as-is would write ``answer: false`` — loads fine (the loader coerces it),
+    but a reader sees ``false``, not the authored ``no``. Canonicalise here so the on-disk text
+    stays the research vocabulary, the same spirit as ``_canonical_kind`` for source kinds.
+    """
+    needs = doc.get("needs")
+    if not isinstance(needs, list):
+        return
+    for raw in cast("list[object]", needs):
+        if isinstance(raw, dict):
+            need = cast("dict[str, object]", raw)
+            if isinstance(need.get("answer"), bool):
+                need["answer"] = "yes" if need["answer"] else "no"
+
+
 def _render_edit(old_text: str, doc: dict[str, object], need_id: str) -> str:
     """Re-render after an in-place edit, splicing only the changed need to keep comments (#53).
 
@@ -175,6 +193,7 @@ def _render_edit(old_text: str, doc: dict[str, object], need_id: str) -> str:
     behaviour) when the file's shape is anything the splice isn't sure of — the reload gate in
     :func:`_validated` guards correctness either way.
     """
+    _normalize_answer(doc)
     lines = old_text.splitlines(keepends=True)
     span = _need_block_span(lines, need_id)
     needs = doc.get("needs")

prodc-0.3.72/tests/test_answer.py

@@ -0,0 +1,154 @@
+"""Research-board `answer` axis: DELIVERED means a question is *settled*; `answer`
+(yes/no/inconclusive) records which way. A settled-NO is a result that still counts toward
+coverage, not a gap. Authored on the Need, never computed — a product board never sets it."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from prodc.config import Config
+from prodc.loader import LoaderError, load
+from prodc.model import Answer, Need
+
+_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+
+[proofs.x]
+kind = "files"
+"""
+
+# N-1 is settled (the files proof resolves) with a NO answer — a disproven hypothesis.
+_NEEDS = """
+needs:
+  - id: N-1
+    text: the Collatz conjecture is false
+    proofs: ["x:1"]
+    answer: no
+  - id: N-2
+    text: a question with no direction recorded
+    proofs: ["x:1"]
+"""
+
+
+def _project(tmp_path: Path, toml: str = _TOML, needs: str = _NEEDS) -> Path:
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text(toml, encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
+    (tmp_path / "1").write_text("ok\n", encoding="utf-8")  # files adapter payload "1" exists
+    return tmp_path / "prodc.toml"
+
+
+# --- model / loader ---------------------------------------------------------
+
+
+def test_loader_parses_answer(tmp_path: Path) -> None:
+    by_id = {n.id: n for n in load(Config.load(_project(tmp_path))).needs}
+    assert by_id["N-1"].answer is Answer.NO
+    assert by_id["N-2"].answer is None  # absent → None, a product need
+
+
+def test_loader_accepts_every_direction(tmp_path: Path) -> None:
+    needs = """
+needs:
+  - id: Y
+    text: settled yes
+    answer: yes
+  - id: N
+    text: settled no
+    answer: no
+  - id: I
+    text: cannot decide
+    answer: inconclusive
+"""
+    by_id = {n.id: n for n in load(Config.load(_project(tmp_path, needs=needs))).needs}
+    assert (by_id["Y"].answer, by_id["N"].answer, by_id["I"].answer) == (
+        Answer.YES,
+        Answer.NO,
+        Answer.INCONCLUSIVE,
+    )
+
+
+def test_loader_errors_on_unknown_answer(tmp_path: Path) -> None:
+    bad = "needs:\n  - id: B\n    text: bad\n    answer: maybe\n"
+    with pytest.raises(LoaderError, match="unknown answer 'maybe'"):
+        load(Config.load(_project(tmp_path, needs=bad)))
+
+
+def test_answer_does_not_touch_coverage_rule() -> None:
+    # answer is a direction, not a coverage axis — a settled-no still counts
+    settled_no = Need(id="X", text="t", proofs=("x:1",), answer=Answer.NO)
+    assert settled_no.counts_toward_coverage is True
+    assert Need(id="X", text="t").answer is None  # default, product need
+
+
+# --- status (coverage + honesty warning) ------------------------------------
+
+
+def test_settled_no_is_delivered_and_counts(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    main(["status", "--config", str(_project(tmp_path)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    by_id = {n["id"]: n for n in payload["needs"]}
+    assert by_id["N-1"]["state"] == "delivered"  # settled
+    assert by_id["N-1"]["answer"] == "no"  # answered NO — a result
+    assert payload["summary"]["delivered"] == 2  # settled-no is delivered, not a gap
+    assert payload["summary"]["total"] == 2
+
+
+def test_warns_when_answer_on_unsettled_question(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    # a HOLE (no proof) carrying an answer — the direction is unsupported
+    needs = "needs:\n  - id: H\n    text: unsettled\n    answer: yes\n"
+    main(["status", "--config", str(_project(tmp_path, needs=needs)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    warnings = payload["needs"][0]["warnings"]
+    assert any("declared on an unsettled question" in w for w in warnings)
+
+
+def test_no_warning_when_answer_on_settled_question(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    main(["status", "--config", str(_project(tmp_path)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    n1 = next(n for n in payload["needs"] if n["id"] == "N-1")
+    assert not any("unsettled question" in w for w in n1["warnings"])  # DELIVERED + no is honest
+
+
+# --- render (show) ----------------------------------------------------------
+
+
+def test_show_renders_answer(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    main(["show", "N-1", "--config", str(_project(tmp_path))])
+    assert "answer: no" in capsys.readouterr().out
+
+
+# --- writer (round-trips through the one-need splice with no writer change) --
+
+
+def test_answer_survives_a_splice_edit(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    cfg = _project(tmp_path)
+    main(["set", "N-1", "importance=3", "--config", str(cfg)])  # edit a different field
+    capsys.readouterr()  # drop the diff
+    by_id = {n.id: n for n in load(Config.load(cfg)).needs}
+    assert by_id["N-1"].answer is Answer.NO  # the authored answer is still there
+    assert by_id["N-1"].importance == 3
+    # on disk it stays the research word, never re-dumped as the YAML bool `false`
+    text = (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
+    assert "answer: 'no'" in text
+    assert "answer: false" not in text

prodc-0.3.72/tests/test_citation.py

@@ -0,0 +1,39 @@
+"""The `citation` proof adapter (research-board step 5): a cited published result as a declared
+DELIVERED. Distinct from `accept` on purpose — `accept` records who signed off, a citation records
+what external result settles the question (the `ref` a reader follows to check it)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from prodc.adapters import CitationAdapter
+from prodc.config import Config
+from prodc.model import ProofState
+
+
+def test_citation_is_declared_delivered() -> None:
+    r = CitationAdapter().resolve("Smith2019@Smith@2019")
+    assert r.state is ProofState.DELIVERED
+    assert r.declared is True  # the `*` marker — declared, not checked by prodc
+    assert r.detail == "cites Smith2019 by Smith (2019)"
+
+
+def test_citation_ref_only() -> None:
+    r = CitationAdapter().resolve("arXiv:2401.00001")
+    assert r.state is ProofState.DELIVERED
+    assert r.detail == "cites arXiv:2401.00001"  # author/year optional
+
+
+def test_citation_never_broken_even_when_empty() -> None:
+    # it is an assertion, like a tag — it never fails to resolve
+    assert CitationAdapter().resolve("").state is ProofState.DELIVERED
+
+
+def test_config_builds_citation_adapter(tmp_path: Path) -> None:
+    (tmp_path / "needs").mkdir()
+    (tmp_path / "prodc.toml").write_text(
+        '[prodc]\nneeds = ["needs/*.yaml"]\n\n[proofs.paper]\nkind = "citation"\n',
+        encoding="utf-8",
+    )
+    cfg = Config.load(tmp_path / "prodc.toml")
+    assert isinstance(cfg.adapters["paper"], CitationAdapter)

prodc-0.3.72/tests/test_claim_gating.py

@@ -0,0 +1,66 @@
+"""The claim-gated text lint — what replaced the product/research profile fork. The EARS /
+solution-verb lint fires only on a need that has NOT stated its `claim` (the warrant). A need that
+articulates its claim has already done the thinking the lint prods toward, so it is silenced — one
+board serves a product PM and a research lab head with no mode. Source hygiene always runs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from prodc.config import Config
+from prodc.loader import load
+from prodc.status import resolve
+
+
+def _warnings(tmp_path: Path, needs: str) -> list[str]:
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text('[prodc]\nneeds = ["needs/*.yaml"]\n', encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
+    cfg = Config.load(tmp_path / "prodc.toml")
+    results = resolve(list(load(cfg).needs), cfg.adapters, cfg.source_adapters)
+    return [w for r in results for w in r.warnings]
+
+
+def test_claimless_need_is_linted(tmp_path: Path) -> None:
+    # a claim with no outcome phrasing and no `claim` field — EARS flags it
+    warnings = _warnings(tmp_path, "needs:\n  - id: Q\n    text: Prove that pi is irrational\n")
+    assert any("EARS" in w for w in warnings)
+
+
+def test_stating_the_claim_silences_the_lint(tmp_path: Path) -> None:
+    # the same text, now with the warrant articulated — the lint is silenced, no mode needed
+    needs = (
+        "needs:\n"
+        "  - id: Q\n"
+        "    text: Prove that pi is irrational\n"
+        "    claim: pi has no rational representation p/q\n"
+    )
+    warnings = _warnings(tmp_path, needs)
+    assert not any("EARS" in w for w in warnings)
+
+
+def test_claim_silences_solution_verb_too(tmp_path: Path) -> None:
+    verb = "needs:\n  - id: Q\n    text: implement the sieve\n"
+    assert any("solution in disguise" in w for w in _warnings(tmp_path, verb))
+    with_claim = verb + "    claim: primes below N are enumerated correctly\n"
+    assert not any("solution in disguise" in w for w in _warnings(tmp_path, with_claim))
+
+
+def test_product_need_without_claim_still_linted(tmp_path: Path) -> None:
+    # the common product case is unchanged: no claim set → the EARS nudge still fires
+    needs = "needs:\n  - id: N\n    text: a vague capability with no outcome word\n"
+    assert any("EARS" in w for w in _warnings(tmp_path, needs))
+
+
+def test_source_hygiene_runs_regardless_of_claim(tmp_path: Path) -> None:
+    # a primary source with no named person is flagged whether or not a claim is stated
+    needs = """
+needs:
+  - id: Q
+    text: a settled claim
+    claim: the thing holds
+    sources:
+      - kind: primary
+        date: 2026-10-11
+"""
+    assert any("primary source without a named person" in w for w in _warnings(tmp_path, needs))

prodc-0.3.72/tests/test_evalgate.py

@@ -0,0 +1,100 @@
+"""The `evalgate` proof adapter (research-board step 4, #75): a scored sibling of the external
+(OutcomeAdapter) proof. It reads a numeric eval score from a results file and gates it against a
+threshold carried in the locator (`accuracy>=0.9`), so one adapter serves many metrics and cutoffs.
+Records-only — prodc reads the recorded score, never runs the eval."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from prodc.adapters import EvalGateAdapter
+from prodc.config import Config, ConfigError
+from prodc.model import ProofState
+
+
+def _adapter(tmp_path: Path, results: object, name: str = "eval.json") -> EvalGateAdapter:
+    (tmp_path / name).write_text(json.dumps(results), encoding="utf-8")
+    return EvalGateAdapter(root=tmp_path, results=name)
+
+
+def test_delivered_when_score_meets_gate(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"accuracy": {"score": 0.82}})
+    r = a.resolve("accuracy>=0.8")
+    assert r.state is ProofState.DELIVERED
+    assert "0.82" in r.detail and "pass" in r.detail
+
+
+def test_pending_when_score_below_gate(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"accuracy": {"score": 0.72}})
+    r = a.resolve("accuracy>=0.8")
+    assert r.state is ProofState.PENDING  # recorded, but not green
+    assert "below gate" in r.detail
+
+
+def test_bare_number_is_accepted_as_a_score(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"f1": 0.9})
+    assert a.resolve("f1>=0.9").state is ProofState.DELIVERED  # >= is inclusive
+
+
+def test_less_than_gate_for_a_loss_metric(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"val_loss": {"score": 0.15}})
+    assert a.resolve("val_loss<=0.2").state is ProofState.DELIVERED
+    assert a.resolve("val_loss<=0.1").state is ProofState.PENDING
+
+
+def test_strict_operators(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"m": 0.5})
+    assert a.resolve("m>0.5").state is ProofState.PENDING  # strict: 0.5 is not > 0.5
+    assert a.resolve("m<0.6").state is ProofState.DELIVERED
+
+
+def test_pending_when_metric_absent_from_present_file(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"accuracy": {"score": 0.82}})
+    r = a.resolve("recall>=0.8")
+    assert r.state is ProofState.PENDING  # file read, metric not recorded yet
+    assert "not in results" in r.detail
+
+
+def test_broken_when_results_file_absent(tmp_path: Path) -> None:
+    a = EvalGateAdapter(root=tmp_path, results="missing.json")  # never written
+    r = a.resolve("accuracy>=0.8")
+    assert r.state is ProofState.BROKEN
+    assert "no results file" in r.detail
+
+
+def test_broken_on_malformed_locator(tmp_path: Path) -> None:
+    a = _adapter(tmp_path, {"accuracy": {"score": 0.82}})
+    assert a.resolve("accuracy").state is ProofState.BROKEN  # no operator
+    assert a.resolve("accuracy>=high").state is ProofState.BROKEN  # threshold not a number
+
+
+def test_bool_is_not_a_score(tmp_path: Path) -> None:
+    # a pass/fail bool belongs to the external adapter, not the gate — treated as absent
+    a = _adapter(tmp_path, {"flag": True})
+    assert a.resolve("flag>=0.5").state is ProofState.PENDING
+
+
+# --- config wiring ----------------------------------------------------------
+
+
+def test_config_builds_evalgate_adapter(tmp_path: Path) -> None:
+    (tmp_path / "needs").mkdir()
+    (tmp_path / "prodc.toml").write_text(
+        '[prodc]\nneeds = ["needs/*.yaml"]\n\n'
+        '[proofs.eval]\nkind = "evalgate"\nresults = "eval.json"\n',
+        encoding="utf-8",
+    )
+    cfg = Config.load(tmp_path / "prodc.toml")
+    assert isinstance(cfg.adapters["eval"], EvalGateAdapter)
+
+
+def test_config_evalgate_requires_results(tmp_path: Path) -> None:
+    (tmp_path / "prodc.toml").write_text(
+        '[prodc]\nneeds = ["needs/*.yaml"]\n\n[proofs.eval]\nkind = "evalgate"\n',
+        encoding="utf-8",
+    )
+    with pytest.raises(ConfigError, match="evalgate needs results"):
+        Config.load(tmp_path / "prodc.toml")

prodc-0.3.72/tests/test_needref.py

@@ -0,0 +1,175 @@
+"""The `need:` proof adapter (research-board step 2): a need→need edge for the question→question
+DAG. `need:A` delivers iff A is settled; `need:A@yes` iff A is settled *and* answered that way.
+It rides the proofs tuple and reuses the resolver's cycle detection — no new field, no new edge."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from prodc.config import Config
+from prodc.loader import load
+from prodc.model import Answer, NeedState
+from prodc.status import resolve
+
+_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+
+[proofs.x]
+kind = "files"
+"""
+
+
+def _resolve(tmp_path: Path, needs: str) -> dict[str, NeedState]:
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text(_TOML, encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
+    (tmp_path / "1").write_text("ok\n", encoding="utf-8")  # the files proof `x:1` exists → settled
+    cfg = Config.load(tmp_path / "prodc.toml")
+    model = load(cfg)
+    results = resolve(list(model.needs), cfg.adapters, cfg.source_adapters)
+    return {r.need.id: r.state for r in results}
+
+
+def test_needref_delivers_when_referenced_is_settled(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: A
+    text: lemma A is proven
+    proofs: ["x:1"]
+  - id: B
+    text: theorem B builds on A
+    proofs: ["need:A"]
+""",
+    )
+    assert states["A"] is NeedState.DELIVERED
+    assert states["B"] is NeedState.DELIVERED  # A is settled → B's needref delivers
+
+
+def test_needref_pends_when_referenced_not_settled(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: A
+    text: lemma A, no proof yet
+  - id: B
+    text: theorem B builds on A
+    proofs: ["need:A"]
+""",
+    )
+    assert states["A"] is NeedState.HOLE  # no proof
+    assert states["B"] is NeedState.PENDING  # cannot deliver until A settles
+
+
+def test_needref_broken_on_unknown_id(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: B
+    text: depends on a need that does not exist
+    proofs: ["need:GHOST"]
+""",
+    )
+    assert states["B"] is NeedState.BROKEN
+
+
+def test_needref_directional_matches_authored_answer(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: A
+    text: the counterexample search settled it
+    proofs: ["x:1"]
+    answer: no
+  - id: B
+    text: needs A specifically answered no
+    proofs: ["need:A@no"]
+  - id: C
+    text: needs A answered yes
+    proofs: ["need:A@yes"]
+""",
+    )
+    assert states["A"] is NeedState.DELIVERED
+    assert states["B"] is NeedState.DELIVERED  # A settled AND answered no
+    assert states["C"] is NeedState.PENDING  # A settled, but answered no, not yes
+
+
+def test_needref_directional_pends_when_no_answer_recorded(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: A
+    text: settled but no direction recorded
+    proofs: ["x:1"]
+  - id: B
+    text: wants A answered yes
+    proofs: ["need:A@yes"]
+""",
+    )
+    assert states["A"] is NeedState.DELIVERED
+    assert states["B"] is NeedState.PENDING  # settled, but no answer to match the direction
+
+
+def test_needref_malformed_direction_is_broken(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: A
+    text: settled
+    proofs: ["x:1"]
+  - id: B
+    text: bad direction token
+    proofs: ["need:A@maybe"]
+""",
+    )
+    assert states["B"] is NeedState.BROKEN
+
+
+def test_needref_cycle_is_broken_not_infinite(tmp_path: Path) -> None:
+    states = _resolve(
+        tmp_path,
+        """
+needs:
+  - id: A
+    text: A depends on B
+    proofs: ["need:B"]
+  - id: B
+    text: B depends on A
+    proofs: ["need:A"]
+""",
+    )
+    assert states["A"] is NeedState.BROKEN
+    assert states["B"] is NeedState.BROKEN  # the cycle is caught, resolution terminates
+
+
+def test_needref_b_does_not_inherit_a_answer(tmp_path: Path) -> None:
+    # B depends on A (answered no) but B is its own question with its own answer
+    by_id = {}
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text(_TOML, encoding="utf-8")
+    (tmp_path / "1").write_text("ok\n", encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(
+        """
+needs:
+  - id: A
+    text: A answered no
+    proofs: ["x:1"]
+    answer: no
+  - id: B
+    text: B depends on A, answered yes itself
+    proofs: ["need:A"]
+    answer: yes
+""",
+        encoding="utf-8",
+    )
+    cfg = Config.load(tmp_path / "prodc.toml")
+    by_id = {n.id: n for n in load(cfg).needs}
+    assert by_id["A"].answer is Answer.NO
+    assert by_id["B"].answer is Answer.YES  # B keeps its own answer, not A's

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

@@ -1,24 +0,0 @@
-who: jordan
-label: "design partner"
-needs:
-  - id: N-1
-    text: "see which orders are past due at a glance"
-    must: true
-    sources:
-      - kind: primary
-        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: secondary
-        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