prodc 0.3.66__tar.gz → 0.3.73__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.66
+Version: 0.3.73
 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.73/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.73}/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.73}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.3.66"
+version = "0.3.73"
 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.73}/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.73}/src/prodc/agent.md

@@ -80,8 +80,9 @@ Read first, then act, then check.
 | act on a need going green (notify a tracker, etc.) | `prodc sync` — runs the `[callbacks]` commands for needs whose state changed since the last sync (`--dry-run` to preview) |
 | gate in CI | `prodc lint --strict` |
 
-Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <toml>…`
-(roll up many repos into one scoreboard), and `prodc diff <snapshot.json>` (what changed since a
+Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <path>…`
+(roll up many boards into one scoreboard + totals; a path is a prodc.toml or a dir to discover
+boards under), and `prodc diff <snapshot.json>` (what changed since a
 saved `status --json`). `prodc status` also takes `--goal <id>`, `--columns id,state,text,warrant`,
 `--wide`, `--include-drafts`, and `--stale <days>`.
 

{prodc-0.3.66 → prodc-0.3.73}/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.73}/src/prodc/cli/app.py

@@ -324,8 +324,19 @@ def main(argv: list[str] | None = None) -> int:
     )
     ri.set_defaults(func=cmd_reinstate)
 
-    pf = sub.add_parser("portfolio", help="roll up many repos into one scoreboard")
-    pf.add_argument("configs", nargs="+", metavar="PRODC_TOML", help="one or more prodc.toml paths")
+    pf = sub.add_parser("portfolio", help="roll up many boards into one scoreboard")
+    pf.add_argument(
+        "configs",
+        nargs="+",
+        metavar="PATH",
+        help="prodc.toml paths and/or directories to discover boards under",
+    )
+    pf.add_argument(
+        "--max-depth",
+        type=int,
+        default=4,
+        help="how deep to descend when discovering boards under a directory (default 4)",
+    )
     pf.add_argument("--json", action="store_true", help="machine-readable output")
     pf.set_defaults(func=cmd_portfolio)
 

{prodc-0.3.66 → prodc-0.3.73}/src/prodc/cli/commands.py

@@ -56,7 +56,15 @@ from ..writer import (
     set_importance,
     withdraw,
 )
-from .common import RepoRow, emit_edit, exit_code, git_rev, load_or_report
+from .common import (
+    RepoRow,
+    discover_configs,
+    emit_edit,
+    exit_code,
+    git_rev,
+    load_or_report,
+    portfolio_totals,
+)
 from .render import (
     COLUMNS,
     provenance_counts,
@@ -582,12 +590,33 @@ def _repo_row(config_path: str) -> RepoRow:
 
 
 def cmd_portfolio(args: argparse.Namespace) -> int:
-    """Roll up many repos into one scoreboard — coverage, must-HOLEs, provenance per repo."""
-    rows = [_repo_row(path) for path in args.configs]
+    """Roll up many boards into one scoreboard — coverage, must-HOLEs, provenance per board.
+
+    Each argument is a ``prodc.toml`` path or a directory to discover boards under (every
+    ``prodc.toml`` beneath it, pruning VCS/vendor/build and hidden dirs, capped at ``--max-depth``).
+    Boards stay separate rows; a totals footer aggregates the clean ones. Never a merged board.
+    """
+    paths: list[str] = []
+    for arg in args.configs:
+        p = Path(arg)
+        if p.is_dir():
+            paths.extend(str(c) for c in discover_configs(p, max_depth=args.max_depth))
+        else:
+            paths.append(arg)
+    seen: set[str] = set()
+    unique: list[str] = []
+    for path in paths:
+        key = str(Path(path).resolve())
+        if key not in seen:
+            seen.add(key)
+            unique.append(path)
+    rows = [_repo_row(path) for path in unique]
+    totals = portfolio_totals(rows)
     if args.json:
-        print(json.dumps([asdict(r) for r in rows], indent=2))
+        payload = {"boards": [asdict(r) for r in rows], "totals": asdict(totals)}
+        print(json.dumps(payload, indent=2))
     else:
-        print(render_portfolio(rows))
+        print(render_portfolio(rows, totals))
     return 2 if any(r.error is not None for r in rows) else 0
 
 

{prodc-0.3.66 → prodc-0.3.73}/src/prodc/cli/common.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -100,3 +101,79 @@ class RepoRow:
     coverage: float
     provenance: dict[str, int]
     error: str | None = None
+
+
+@dataclass(frozen=True)
+class PortfolioTotals:
+    """The aggregate across every board in a portfolio — a footer, not a merged board.
+
+    Error rows are excluded (a board that would not load contributes no counts). ``coverage`` is
+    the pooled ``delivered / total``, which is not the mean of the per-board percentages.
+    """
+
+    boards: int  # how many boards loaded cleanly and are summed here
+    delivered: int
+    total: int
+    must_hole: int
+    broken: int
+    coverage: float
+
+
+def portfolio_totals(rows: list[RepoRow]) -> PortfolioTotals:
+    """Sum the clean rows into a :class:`PortfolioTotals` footer."""
+    ok = [r for r in rows if r.error is None]
+    delivered = sum(r.delivered for r in ok)
+    total = sum(r.total for r in ok)
+    return PortfolioTotals(
+        boards=len(ok),
+        delivered=delivered,
+        total=total,
+        must_hole=sum(r.must_hole for r in ok),
+        broken=sum(r.broken for r in ok),
+        coverage=round(delivered / total, 4) if total else 0.0,
+    )
+
+
+# Directory names never descended into during board discovery: VCS, virtualenvs, dependency and
+# build trees. Any name starting with "." is pruned too (handled in the walk), so a vendored or
+# example prodc.toml buried in one of these is never mistaken for a board.
+_PRUNE_DIRS = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "venv",
+        "__pycache__",
+        "dist",
+        "build",
+        "target",
+        ".tox",
+        ".mypy_cache",
+        ".ruff_cache",
+        "site-packages",
+        "vendor",
+    }
+)
+
+
+def discover_configs(root: Path, *, max_depth: int = 4) -> list[Path]:
+    """Every ``prodc.toml`` under ``root``, for the portfolio roll-up — bounded so it can't run away.
+
+    A plain recursive scan is a footgun: it descends into ``.git``/``node_modules``/build trees and
+    picks up vendored or example configs. So this prunes those (and every ``.``-prefixed dir) and
+    caps the descent at ``max_depth`` directories below ``root``. Returns sorted, de-duplicated
+    paths; a board is the directory that holds the ``prodc.toml``.
+    """
+    root = root.resolve()
+    found: set[Path] = set()
+    for dirpath, dirnames, filenames in os.walk(root):
+        if "prodc.toml" in filenames:
+            found.add(Path(dirpath) / "prodc.toml")
+        depth = len(Path(dirpath).relative_to(root).parts)
+        # Prune in place so os.walk never descends into the skipped dirs, then stop at the depth cap.
+        dirnames[:] = (
+            []
+            if depth >= max_depth
+            else [d for d in dirnames if d not in _PRUNE_DIRS and not d.startswith(".")]
+        )
+    return sorted(found)

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

@@ -22,7 +22,7 @@ from ..model import (
     ears_shape,
 )
 from ..status import Handoff, Recurrence, Summary, rank, state_priority
-from .common import RepoRow, brief_open
+from .common import PortfolioTotals, RepoRow, brief_open
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -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:
@@ -378,7 +380,9 @@ def render_argument(model: Model, defects: list[str]) -> str:
     return "\n".join(out)
 
 
-def render_portfolio(rows: list[RepoRow]) -> str:
+def render_portfolio(rows: list[RepoRow], totals: PortfolioTotals | None = None) -> str:
+    if not rows:
+        return "  no boards found"
     out = [f"  {'repo':<18} {'cov':>4}  {'must-HOLE':>9}  {'BROKEN':>6}   prov prim/sec/asm/op"]
     for row in rows:
         if row.error is not None:
@@ -388,4 +392,12 @@ def render_portfolio(rows: list[RepoRow]) -> str:
         prov = f"{p['primary']}/{p['secondary']}/{p['assumption']}/{p['opinion']}"
         cov = f"{round(row.coverage * 100)}%"
         out.append(f"  {row.repo:<18} {cov:>4}  {row.must_hole:>9}  {row.broken:>6}   {prov}")
+    if totals is not None:
+        cov = f"{round(totals.coverage * 100)}%"
+        label = f"TOTAL ({totals.boards} boards)"
+        out.append(f"  {'─' * 48}")
+        out.append(
+            f"  {label:<18} {cov:>4}  {totals.must_hole:>9}  {totals.broken:>6}   "
+            f"{totals.delivered}/{totals.total} delivered"
+        )
     return "\n".join(out)

{prodc-0.3.66 → prodc-0.3.73}/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.73}/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.73}/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)