prodc 0.3.80__tar.gz → 0.3.82__tar.gz

{prodc-0.3.80 → prodc-0.3.82}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.80
+Version: 0.3.82
 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.80 → prodc-0.3.82}/pyproject.toml

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

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/agent.md

@@ -74,6 +74,8 @@ Read first, then act, then check.
 | declare a role (the roster) | `prodc add role <id> --text "…" --file needs/<f>.yaml` |
 | declare a product principle (the vision, held as given) | `prodc add principle <id> --text "…" --file needs/<f>.yaml` — the frame that decides between clients who want opposite things; what an `out_of_scope` decision cites |
 | revise a principle (fires the re-review ripple) | `prodc revise principle <id> [--text "…"] [--date ISO]` — re-stamps `revised_at`, so every need withdrawn under it with an earlier date comes back up |
+| promote a need you commit to into a principle | `prodc add principle <id> --from-need <need-id> --file needs/<f>.yaml` — copies the need's text (unless `--text` overrides) and its sources (the client signals that surfaced it); the need stays on the board, so a need and the principle it inspired coexist |
+| record how a need gets built (the chosen solution) | `prodc add decision <id> --text "<the solution>" --needs <ids> [--alternative "<rejected>" …] [--consequences "…"] [--principles <ids>] --file needs/<f>.yaml` — the OST node: which solution you picked for a need, over what, resting on which principle. `--needs` is required (a decision with no need is refused); `lint` flags one left serving only withdrawn needs, or decided before a principle it cites was revised |
 | attach evidence after a user said something | `prodc capture <id> --kind primary --who <person> [--role <id>] --date <ISO> --quote "…"` (`--role` records which declared role vouched for it) |
 | set or append a field | `prodc set <id> key=value` (append a list with `key+=value`, e.g. `proofs+=web:orders.feature#…`) |
 | mark two needs as opposing each other | `prodc set <id> contradicts+=<other-id>` — symmetric (declare once); `lint` flags a pair left both-live (clients want opposite things and the vision has not decided), and `withdraw … --kind out_of_scope --principle <id>` resolves it |

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/cli/app.py

@@ -167,14 +167,59 @@ def main(argv: list[str] | None = None) -> int:
 
     ad = sub.add_parser(
         "add",
-        help="create a new agent-authored need, or declare a role or a principle (writes YAML)",
+        help="create a need, or declare a role, a principle, or a decision (writes YAML)",
     )
-    ad.add_argument("noun", choices=["need", "role", "principle"], help="what to add")
+    ad.add_argument("noun", choices=["need", "role", "principle", "decision"], help="what to add")
     ad.add_argument(
         "need_id",
-        help="the new need's id (or role id for `add role`, principle id for `add principle`), e.g. N-9",
+        help="the new item's id — need (N-9), role, principle (P-1), or decision (D-1)",
+    )
+    ad.add_argument(
+        "--text",
+        default=None,
+        help="the need text (or the role / principle text); required except `add principle "
+        "--from-need`, which takes the text from the need",
+    )
+    ad.add_argument(
+        "--from-need",
+        default=None,
+        metavar="ID",
+        help="principle only: promote a need into a principle — copy its text (unless --text "
+        "overrides) and its sources as the provenance that surfaced it; the need stays on the board",
+    )
+    ad.add_argument(
+        "--needs",
+        default=None,
+        metavar="IDS",
+        help="decision only: comma-separated ids of the needs this decision serves (required; "
+        "validated at load)",
+    )
+    ad.add_argument(
+        "--alternative",
+        action="append",
+        default=None,
+        dest="alternatives",
+        metavar="TEXT",
+        help="decision only: an option that was rejected (repeatable) — what makes it a choice",
+    )
+    ad.add_argument(
+        "--consequences",
+        default=None,
+        help="decision only: what the chosen solution costs / rules out",
+    )
+    ad.add_argument(
+        "--principles",
+        default=None,
+        metavar="IDS",
+        help="decision only: comma-separated principle ids the decision rests on (validated); "
+        "revising one flags the decision stale",
+    )
+    ad.add_argument(
+        "--date",
+        default=None,
+        metavar="ISO",
+        help="decision only: when it was decided (default: today) — the comparand for the ripple",
     )
-    ad.add_argument("--text", required=True, help="the need text (or the role / principle text)")
     ad.add_argument(
         "--who",
         default=None,

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/cli/commands.py

@@ -37,19 +37,23 @@ from ..status import (
     applicable_needs,
     argument_defects,
     contradictions,
+    decisions_for,
     evidence_age_days,
     importance_revisit_due,
+    orphaned_decisions,
     principle_report,
     proof_suggestions,
     recurrence,
     relink_suggestions,
     resolve,
+    stale_decisions,
     summarize,
 )
 from ..writer import (
     Edit,
     WriteError,
     accept,
+    add_decision,
     add_need,
     add_principle,
     add_proof,
@@ -81,6 +85,7 @@ from .render import (
     render_argument,
     render_brief,
     render_columns,
+    render_decisions,
     render_goals,
     render_handoffs,
     render_orphans,
@@ -263,6 +268,24 @@ def cmd_lint(args: argparse.Namespace) -> int:
     warnings = [
         (r.need.id, w) for r in sorted(results, key=lambda x: x.need.id) for w in r.warnings
     ]
+    # Decision drift (keyed by the decision id, not a need): a decision left serving only
+    # withdrawn/non-product needs is engineering with no live product reason; a decision decided
+    # under a principle that was revised later comes back up (the same ripple a withdrawal gets).
+    decisions = list(model.decisions)
+    for d in orphaned_decisions(decisions, needs):
+        warnings.append(
+            (
+                d.id,
+                "decision serves only withdrawn/non-product needs — re-tie it to a live need or withdraw it",
+            )
+        )
+    for d, pid in stale_decisions(decisions, list(model.principles)):
+        warnings.append(
+            (
+                d.id,
+                f"decided {d.decided_at} under principle {pid}, revised later — re-review this solution",
+            )
+        )
     if args.json:
         print(
             json.dumps(
@@ -346,6 +369,7 @@ def cmd_status(args: argparse.Namespace) -> int:
                 unroled,
                 hos,
                 principles=board.principles,
+                decisions=list(model.decisions),
             )
         )
     else:
@@ -380,6 +404,8 @@ def cmd_status(args: argparse.Namespace) -> int:
             print(render_recurrence(recs))
         if model.principles:
             print(render_principles(board.principles))
+        if model.decisions:
+            print(render_decisions(list(model.decisions), needs=list(model.needs)))
         if orphan_map:
             print(render_orphans(orphan_map))
 
@@ -397,7 +423,12 @@ def cmd_show(args: argparse.Namespace) -> int:
     if r is None:
         print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
         return 2
-    print(show_json(r) if args.json else render_show(r, cfg.importance_label(r.need.importance)))
+    decisions = decisions_for(args.need_id, list(model.decisions))  # the 'how' behind this need
+    print(
+        show_json(r, decisions=decisions)
+        if args.json
+        else render_show(r, cfg.importance_label(r.need.importance), decisions=decisions)
+    )
     return 0
 
 
@@ -495,6 +526,9 @@ def cmd_add(args: argparse.Namespace) -> int:
         print(f"prodc: no config at {cfg_path}", file=sys.stderr)
         return 2
     if args.noun == "role":
+        if args.text is None:
+            print("prodc: add role requires --text", file=sys.stderr)
+            return 2
         try:
             cfg = Config.load(cfg_path)
             edit = add_role(
@@ -512,12 +546,62 @@ def cmd_add(args: argparse.Namespace) -> int:
     if args.noun == "principle":
         try:
             cfg = Config.load(cfg_path)
+            text, sources = args.text, ()
+            if args.from_need:
+                # Promote a need into a principle (the discovery lifecycle): the signals that
+                # surfaced it travel with it as provenance, so the history stays honest. The origin
+                # need stays on the board unchanged — a need and the principle it inspired coexist.
+                origin = next((n for n in load(cfg).needs if n.id == args.from_need), None)
+                if origin is None:
+                    print(f"prodc: no need '{args.from_need}' to promote", file=sys.stderr)
+                    return 2
+                text = args.text or origin.text
+                sources = origin.sources
+            if text is None:
+                print(
+                    "prodc: add principle requires --text (or --from-need to take it from a need)",
+                    file=sys.stderr,
+                )
+                return 2
             edit = add_principle(
                 cfg,
                 args.need_id,
-                args.text,
+                text,
                 file=args.file,
                 revised_at=date.today().isoformat(),
+                sources=sources,
+                expect_sha=args.expect_sha,
+                dry_run=args.dry_run,
+            )
+        except (ConfigError, LoaderError, WriteError) as exc:
+            print(f"prodc: {exc}", file=sys.stderr)
+            return 2
+        return emit_edit(edit, args.dry_run, args.json)
+    if args.noun == "decision":
+        if args.text is None:
+            print("prodc: add decision requires --text (the chosen solution)", file=sys.stderr)
+            return 2
+        needs = tuple(n.strip() for n in (args.needs or "").split(",") if n.strip())
+        if not needs:
+            print(
+                "prodc: add decision requires --needs (the need(s) the solution serves)",
+                file=sys.stderr,
+            )
+            return 2
+        principles = tuple(p.strip() for p in (args.principles or "").split(",") if p.strip())
+        try:
+            cfg = Config.load(cfg_path)
+            edit = add_decision(
+                cfg,
+                args.need_id,
+                args.text,
+                file=args.file,
+                needs=needs,
+                decided_at=args.date or date.today().isoformat(),
+                alternatives=tuple(args.alternatives or ()),
+                consequences=args.consequences,
+                principles=principles,
+                draft=args.draft,
                 expect_sha=args.expect_sha,
                 dry_run=args.dry_run,
             )
@@ -528,6 +612,9 @@ def cmd_add(args: argparse.Namespace) -> int:
     if args.who is None:
         print("prodc: add need requires --who (the author recorded on the source)", file=sys.stderr)
         return 2
+    if args.text is None:
+        print("prodc: add need requires --text", file=sys.stderr)
+        return 2
     try:
         cfg = Config.load(cfg_path)
         if not args.no_dupe_check:

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/cli/render.py

@@ -12,6 +12,7 @@ from collections.abc import Callable
 
 from ..board import warrant as _warrant
 from ..model import (
+    Decision,
     Goal,
     Model,
     Need,
@@ -21,7 +22,15 @@ from ..model import (
     Role,
     ears_shape,
 )
-from ..status import Handoff, PrincipleReport, Recurrence, Summary, rank, state_priority
+from ..status import (
+    Handoff,
+    PrincipleReport,
+    Recurrence,
+    Summary,
+    orphaned_decisions,
+    rank,
+    state_priority,
+)
 from .common import PortfolioTotals, RepoRow, brief_open
 
 _LABEL = {
@@ -280,7 +289,34 @@ def render_principles(reports: list[PrincipleReport]) -> str:
     return "\n".join(out)
 
 
-def render_show(r: NeedResult, importance_label: str | None = None) -> str:
+def render_decisions(decisions: list[Decision], needs: list[Need]) -> str:
+    """The solution chosen for each need (OST), what it rejected, and the needs it serves.
+
+    Shows the decisions still in force (a superseded one is off the board, its record kept). A
+    decision left serving only withdrawn/non-product needs is flagged orphaned — the 'how' lost its
+    'what'.
+    """
+    orphans = {d.id for d in orphaned_decisions(decisions, needs)}
+    active = sorted((d for d in decisions if d.withdrawn is None), key=lambda x: x.id)
+    out = ["\ndecisions (the solution chosen for a need — how it gets built):"]
+    for d in active:
+        tag = " (proposed)" if d.draft else ""
+        out.append(f"  {d.id:<6}{tag} {d.text}")
+        out.append(f"        serves: {', '.join(d.needs)}")
+        if d.alternatives:
+            out.append(f"        over: {', '.join(d.alternatives)}")
+        if d.principles:
+            out.append(f"        rests on: {', '.join(d.principles)}")
+        if d.id in orphans:
+            out.append("        ⚠ serves only withdrawn/non-product needs — re-tie or withdraw")
+    return "\n".join(out)
+
+
+def render_show(
+    r: NeedResult,
+    importance_label: str | None = None,
+    decisions: list[Decision] | None = None,
+) -> str:
     """One need as a citable answer — the artifact you drop into a thread."""
     need = r.need
     who = (need.who + (f" ({need.label})" if need.label else "")) if need.who else "(unassigned)"
@@ -349,6 +385,11 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
         lines += [f"    - {d}" for d in r.detail]
     elif not need.children:
         lines.append("  proofs: (none — HOLE)")
+    if decisions:
+        lines.append("  decisions (how it's built):")
+        for d in decisions:
+            alt = f"  (over {', '.join(d.alternatives)})" if d.alternatives else ""
+            lines.append(f"    - {d.id}: {d.text}{alt}")
     lines += [f"  ⚠ {w}" for w in r.warnings]
     return "\n".join(lines)
 

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/cli/serialize.py

@@ -12,11 +12,35 @@ import json
 from ..board import need_payload
 from ..board import warrant as _warrant
 from ..dedup import DupPair, VariantGroup
-from ..model import Goal, Model, NeedResult, NeedState, Release, Role
+from ..model import Decision, Goal, Model, NeedResult, NeedState, Release, Role
 from ..status import Handoff, PrincipleReport, Recurrence, Summary, rank
 from .common import brief_open
 
 
+def _decision_payload(d: Decision) -> dict[str, object]:
+    """One decision as a JSON record — the OST chosen-solution node and its edges."""
+    return {
+        "id": d.id,
+        "text": d.text,
+        "needs": list(d.needs),
+        "alternatives": list(d.alternatives),
+        "consequences": d.consequences,
+        "principles": list(d.principles),
+        "decided_at": d.decided_at,
+        "draft": d.draft,
+        "withdrawn": (
+            {
+                "reason": d.withdrawn.reason,
+                "date": d.withdrawn.date,
+                "kind": d.withdrawn.kind.value,
+                "principle": d.withdrawn.principle,
+            }
+            if d.withdrawn
+            else None
+        ),
+    }
+
+
 def _summary_payload(summary: Summary, orphan_map: dict[str, list[str]]) -> dict[str, object]:
     return {
         "total": summary.total,
@@ -44,6 +68,7 @@ def to_json(
     unroled: list[NeedResult],
     hos: list[Handoff],
     principles: list[PrincipleReport] | None = None,
+    decisions: list[Decision] | None = None,
 ) -> str:
     payload = {
         "summary": _summary_payload(summary, orphan_map),
@@ -111,17 +136,19 @@ def to_json(
             }
             for rep in (principles or [])
         ],
+        "decisions": [_decision_payload(d) for d in (decisions or [])],
         "needs": [need_payload(r) for r in results],
     }
     return json.dumps(payload, indent=2)
 
 
-def show_json(r: NeedResult) -> str:
+def show_json(r: NeedResult, decisions: list[Decision] | None = None) -> str:
     need = r.need
     payload = need_payload(r)  # the shared core — never drifts from the board
     payload.update(
         {
             "label": need.label,
+            "decisions": [_decision_payload(d) for d in (decisions or [])],
             "sources": [
                 {
                     "kind": s.kind.value,

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/loader.py

@@ -22,6 +22,7 @@ from .model import (
     ArgNode,
     Attestation,
     AttestationKind,
+    Decision,
     Goal,
     Model,
     Need,
@@ -326,6 +327,39 @@ def _principle(raw: object, where: str) -> Principle:
     )
 
 
+def _decision(raw: object, where: str) -> Decision:
+    """Parse one ``decisions:`` entry — the solution chosen for a need, and what was rejected.
+
+    ``needs`` is required and must be non-empty: a decision with no need it serves is engineering
+    with no product reason, refused here rather than nagged at by a soft lint. ``withdrawn`` reuses
+    the Need withdrawal (a superseded decision keeps its record).
+    """
+    tbl = _as_mapping(raw, where)
+    needs = tuple(
+        _as_str(n, f"{where}.needs[{i}]")
+        for i, n in enumerate(_as_list(tbl.get("needs"), f"{where}.needs"))
+    )
+    if not needs:
+        raise LoaderError(f"{where}: a decision must serve at least one need (needs: [...])")
+    return Decision(
+        id=_as_str(tbl.get("id"), f"{where}.id"),
+        text=_as_str(tbl.get("text"), f"{where}.text"),
+        needs=needs,
+        alternatives=tuple(
+            _as_str(a, f"{where}.alternatives[{i}]")
+            for i, a in enumerate(_as_list(tbl.get("alternatives"), f"{where}.alternatives"))
+        ),
+        consequences=_opt_str(tbl.get("consequences"), f"{where}.consequences"),
+        principles=tuple(
+            _as_str(p, f"{where}.principles[{i}]")
+            for i, p in enumerate(_as_list(tbl.get("principles"), f"{where}.principles"))
+        ),
+        decided_at=_opt_str(tbl.get("decided_at"), f"{where}.decided_at"),
+        draft=_as_bool(tbl["draft"], f"{where}.draft") if "draft" in tbl else False,
+        withdrawn=_withdrawal(tbl.get("withdrawn"), f"{where}.withdrawn"),
+    )
+
+
 def _arg_node(raw: object, where: str) -> ArgNode:
     tbl = _as_mapping(raw, where)
     kind_name = _as_str(tbl.get("kind"), f"{where}.kind")
@@ -359,6 +393,7 @@ class _Loaded:
     releases: list[Release] = field(default_factory=list[Release])
     roles: list[Role] = field(default_factory=list[Role])
     principles: list[Principle] = field(default_factory=list[Principle])
+    decisions: list[Decision] = field(default_factory=list[Decision])
     argument: list[ArgNode] = field(default_factory=list[ArgNode])
 
 
@@ -403,6 +438,10 @@ def _load_file(path: Path, seen: dict[str, dict[str, Path]]) -> _Loaded:
         principle = _principle(raw, f"{where}.principles[{i}]")
         _unique("principle", principle.id)
         out.principles.append(principle)
+    for i, raw in enumerate(_as_list(tbl.get("decisions"), f"{where}.decisions")):
+        decision = _decision(raw, f"{where}.decisions[{i}]")
+        _unique("decision", decision.id)
+        out.decisions.append(decision)
     for i, raw in enumerate(_as_list(tbl.get("argument"), f"{where}.argument")):
         node = _arg_node(raw, f"{where}.argument[{i}]")
         _unique("argument node", node.id)
@@ -427,6 +466,7 @@ def load(config: Config) -> Model:
         "release": {},
         "role": {},
         "principle": {},
+        "decision": {},
         "argument node": {},
     }
     for pattern in config.need_globs:
@@ -437,6 +477,7 @@ def load(config: Config) -> Model:
             acc.releases.extend(f.releases)
             acc.roles.extend(f.roles)
             acc.principles.extend(f.principles)
+            acc.decisions.extend(f.decisions)
             acc.argument.extend(f.argument)
     _check_variants(acc.needs)
     _check_children(acc.needs)
@@ -451,6 +492,7 @@ def load(config: Config) -> Model:
         {a.id for a in acc.principles},
     )
     _check_source_roles(acc.needs, acc.principles, {p.id for p in acc.roles})
+    _check_decisions(acc.decisions, {n.id for n in acc.needs}, {p.id for p in acc.principles})
     _check_argument(acc.argument)
     acc.needs = _symmetrize_contradicts(acc.needs)
     return Model(
@@ -459,6 +501,7 @@ def load(config: Config) -> Model:
         releases=tuple(acc.releases),
         roles=tuple(acc.roles),
         principles=tuple(acc.principles),
+        decisions=tuple(acc.decisions),
         argument=tuple(acc.argument),
     )
 
@@ -521,6 +564,31 @@ def _check_children(needs: list[Need]) -> None:
                 raise LoaderError(f"need {need.id!r}: child {cid!r} is not a known need id")
 
 
+def _check_decisions(
+    decisions: list[Decision], known_needs: set[str], known_principles: set[str]
+) -> None:
+    """Every ``needs`` / ``principles`` id on a decision must name a known need / principle.
+
+    ``needs`` is already guaranteed non-empty by :func:`_decision`; here each id is checked to
+    exist, the same hard-error treatment the other cross-references get. A superseded decision's
+    ``withdrawn.principle`` is checked too, so a stale citation cannot hide on a retired record.
+    """
+    for d in decisions:
+        for nid in d.needs:
+            if nid not in known_needs:
+                raise LoaderError(f"decision {d.id!r}: needs {nid!r} is not a known need id")
+        for pid in d.principles:
+            if pid not in known_principles:
+                raise LoaderError(
+                    f"decision {d.id!r}: principle {pid!r} is not a known principle id"
+                )
+        if d.withdrawn and d.withdrawn.principle and d.withdrawn.principle not in known_principles:
+            raise LoaderError(
+                f"decision {d.id!r}: withdrawn principle {d.withdrawn.principle!r} "
+                "is not a known principle id"
+            )
+
+
 def _check_contradicts(needs: list[Need]) -> None:
     """Every id in a need's ``contradicts`` must name a known need, and never the need itself."""
     known = {n.id for n in needs}

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/model.py

@@ -162,6 +162,33 @@ class Principle:
     sources: tuple[Source, ...] = ()  # the signals that surfaced it — provenance, not validation
 
 
+@dataclass(frozen=True)
+class Decision:
+    """How a need gets built: the solution chosen for it, and the alternatives rejected.
+
+    Not an ADR (an engineer's record) but the Opportunity-Solution-Tree node (Torres): a need is
+    the opportunity, and a decision is *the solution picked for it over the ones considered*. prodc
+    pushes solutions out of :class:`Need` (the solution-verb lint), so this is their only honest
+    home. ``text`` is the chosen solution; ``alternatives`` are what was rejected — without them a
+    decision is a memo, not a choice. ``needs`` is required (a decision with no need it serves is
+    engineering with no product reason, which the loader refuses), and ``principles`` ties the
+    choice to the vision it rests on, so revising a principle after ``decided_at`` flags the
+    decision stale — the same ripple a withdrawal gets. Like a Principle it never enters coverage,
+    the plan, or the opinion check; its lifecycle reuses the Need verbs (``draft`` = proposed,
+    ``withdrawn`` = superseded, keeping the record) rather than a status enum of its own.
+    """
+
+    id: str
+    text: str  # the chosen solution
+    needs: tuple[str, ...]  # the needs this decision serves — required, validated at load
+    alternatives: tuple[str, ...] = ()  # the options rejected — what makes it a choice, not a memo
+    consequences: str | None = None  # what the choice costs / rules out
+    principles: tuple[str, ...] = ()  # the principle(s) it rests on; revising one ripples to here
+    decided_at: str | None = None  # ISO date decided — the comparand for the principle ripple
+    draft: bool = False  # proposed, not yet committed (reuses the Need draft lifecycle)
+    withdrawn: Withdrawal | None = None  # superseded / abandoned — the record stays as its trace
+
+
 class AttestationKind(StrEnum):
     """Who reviewed the warrant — a ladder of strength, human strongest (cf. SourceKind)."""
 
@@ -375,6 +402,7 @@ class Model:
     releases: tuple[Release, ...] = ()  # in declared order = ship sequence
     roles: tuple[Role, ...] = ()  # the roles needs' `who` play (#52)
     principles: tuple[Principle, ...] = ()  # the product vision, held as given
+    decisions: tuple[Decision, ...] = ()  # the solutions chosen for needs (OST), with alternatives
     argument: tuple[ArgNode, ...] = ()  # the GSN assurance graph (#28)
 
 

{prodc-0.3.80 → prodc-0.3.82}/src/prodc/status.py

@@ -19,6 +19,7 @@ from .model import (
     ArgKind,
     ArgNode,
     AttestationKind,
+    Decision,
     Goal,
     Need,
     NeedResult,
@@ -679,6 +680,55 @@ def principle_report(needs: list[Need], principles: list[Principle]) -> list[Pri
     return out
 
 
+def active_decisions(decisions: list[Decision]) -> list[Decision]:
+    """The decisions still in force — neither superseded (``withdrawn``) nor a staged ``draft``."""
+    return [d for d in decisions if d.withdrawn is None and not d.draft]
+
+
+def decisions_for(need_id: str, decisions: list[Decision]) -> list[Decision]:
+    """The in-force decisions whose chosen solution serves ``need_id`` — the 'how' behind a need."""
+    return [d for d in active_decisions(decisions) if need_id in d.needs]
+
+
+def stale_decisions(
+    decisions: list[Decision], principles: list[Principle]
+) -> list[tuple[Decision, str]]:
+    """Each in-force decision paired with a principle it cites that was revised after it was decided.
+
+    The same ripple a withdrawal gets (:func:`principle_report`), the other way round: a solution
+    chosen under an older statement of a principle comes back up when the principle moves. Reuses
+    :func:`_decided_before`; an undated decision or principle never counts (nothing to compare).
+    """
+    revised = {p.id: p.revised_at for p in principles}
+    out: list[tuple[Decision, str]] = []
+    for d in active_decisions(decisions):
+        for pid in d.principles:
+            if pid in revised and _decided_before(d.decided_at or "", revised[pid]):
+                out.append((d, pid))
+    return out
+
+
+def orphaned_decisions(decisions: list[Decision], needs: list[Need]) -> list[Decision]:
+    """In-force decisions whose every served need is withdrawn or non-product — the real orphan.
+
+    A decision must name a need at load, but that need can later be withdrawn (``out_of_scope``) or
+    marked non-product. A decision left serving only such needs is engineering with no live product
+    reason — re-tie it to a live need, or withdraw it. (A need not in ``needs`` at all is a load
+    error, never reached here.)
+    """
+    by_id = {n.id: n for n in needs}
+    out: list[Decision] = []
+    for d in active_decisions(decisions):
+        live = [
+            nid
+            for nid in d.needs
+            if (n := by_id.get(nid)) is not None and not n.is_withdrawn and n.product
+        ]
+        if not live:
+            out.append(d)
+    return out
+
+
 @dataclass(frozen=True)
 class Contradiction:
     """Two needs in tension — clients wanting opposite things. ``unresolved`` = both still live.