prodc 0.3.76__tar.gz → 0.3.77__tar.gz

{prodc-0.3.76 → prodc-0.3.77}/PKG-INFO

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

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

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/agent.md

@@ -79,7 +79,7 @@ Read first, then act, then check.
 | link a recurring want to a shared baseline | `prodc recurrence --suggest --apply --baseline-id <id> --file needs/<f>.yaml` |
 | record a human/AI review of the warrant | `prodc attest <id> --by <who> --date <ISO> [--ai]` |
 | record a human acceptance pass | `prodc accept <id> --who <person> --date <ISO>` |
-| decide against a need (won't-do) | `prodc withdraw <id> --reason "…"` — off the board + out of coverage; `prodc reinstate <id>` puts it back |
+| decide against a need (won't-do) | `prodc withdraw <id> --reason "…" [--kind out_of_scope\|duplicate]` — off the board + out of coverage (use `out_of_scope` for a real need that isn't this product); `prodc reinstate <id>` puts it back |
 | hand a human a readable status file | `prodc report -o status.md` (markdown; `--format html` for an interactive viewer; `--client ID` to scope) |
 | 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` |

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/board.py

@@ -102,7 +102,11 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
             "claim": need.claim,
             "answer": need.answer.value if need.answer else None,
             "withdrawn": (
-                {"reason": need.withdrawn.reason, "date": need.withdrawn.date}
+                {
+                    "reason": need.withdrawn.reason,
+                    "date": need.withdrawn.date,
+                    "kind": need.withdrawn.kind.value,
+                }
                 if need.withdrawn
                 else None
             ),
@@ -150,7 +154,11 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
         "draft": need.draft,
         "answer": need.answer.value if need.answer else None,
         "withdrawn": (
-            {"reason": need.withdrawn.reason, "date": need.withdrawn.date}
+            {
+                "reason": need.withdrawn.reason,
+                "date": need.withdrawn.date,
+                "kind": need.withdrawn.kind.value,
+            }
             if need.withdrawn
             else None
         ),

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/cli/app.py

@@ -300,6 +300,13 @@ def main(argv: list[str] | None = None) -> int:
     wd.add_argument(
         "--reason", required=True, help="why it was decided against (kept on the record)"
     )
+    wd.add_argument(
+        "--kind",
+        choices=["wont_do", "out_of_scope", "duplicate"],
+        default="wont_do",
+        help="the decision's kind: wont_do (default), out_of_scope (real but not this product), "
+        "or duplicate (#74)",
+    )
     wd.add_argument("--date", default=None, help="when (ISO, e.g. 2026-10-10; default: today)")
     wd.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
     wd.add_argument("--json", action="store_true", help="machine-readable output")

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/cli/commands.py

@@ -263,6 +263,14 @@ def cmd_status(args: argparse.Namespace) -> int:
     # orphans) until promoted with `set <id> draft=false`, unless --include-drafts is passed.
     draft_count = sum(1 for n in needs if n.draft and not n.is_withdrawn)
     withdrawn_count = sum(1 for n in needs if n.is_withdrawn)
+    # Break withdrawals down by kind (#74 follow-up), so "declined but valid" (out_of_scope) is
+    # legible on the board apart from plain won't-do; wont_do is the implicit default, not listed.
+    withdrawn_kinds: dict[str, int] = {}
+    for n in needs:
+        if n.withdrawn and n.withdrawn.kind.value != "wont_do":
+            withdrawn_kinds[n.withdrawn.kind.value] = (
+                withdrawn_kinds.get(n.withdrawn.kind.value, 0) + 1
+            )
     needs = board_needs(needs, include_drafts=args.include_drafts)
     # Scoped coverage (#49): restrict the board + coverage to a subset, so the number people
     # act on (this client, this goal) isn't diluted by the whole mixed board.
@@ -318,7 +326,9 @@ def cmd_status(args: argparse.Namespace) -> int:
         if draft_count and not args.include_drafts:
             print(f"drafts: {draft_count} staged (hidden — --include-drafts to show) (#60)")
         if withdrawn_count:
-            print(f"withdrawn: {withdrawn_count} (decided against) (#74)")
+            extra = ", ".join(f"{c} {k}" for k, c in sorted(withdrawn_kinds.items()))
+            suffix = f" — {extra}" if extra else ""
+            print(f"withdrawn: {withdrawn_count} (decided against){suffix} (#74)")
         visible = [r for r in results if r.need.product]
         if args.only_must:
             visible = [r for r in visible if r.need.must]
@@ -549,6 +559,7 @@ def cmd_withdraw(args: argparse.Namespace) -> int:
             args.need_id,
             reason=args.reason,
             date=args.date or date.today().isoformat(),
+            kind=args.kind,
             expect_sha=args.expect_sha,
             dry_run=args.dry_run,
         )

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/cli/render.py

@@ -276,7 +276,9 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
     if need.answer:
         lines.append(f"  answer: {need.answer.value}")
     if need.withdrawn:
-        lines.append(f"  withdrawn: {need.withdrawn.reason} ({need.withdrawn.date})")
+        w = need.withdrawn
+        tag = "" if w.kind.value == "wont_do" else f" [{w.kind.value}]"
+        lines.append(f"  withdrawn{tag}: {w.reason} ({w.date})")
     if need.description:
         lines.append(f"  description: {need.description}")
     if need.importance is not None:

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/loader.py

@@ -30,6 +30,7 @@ from .model import (
     Source,
     SourceKind,
     Withdrawal,
+    WithdrawalKind,
 )
 
 
@@ -130,10 +131,12 @@ def _answer(raw: object, where: str) -> Answer | None:
 
 
 def _withdrawal(raw: object, where: str) -> Withdrawal | None:
-    """Parse ``withdrawn: {reason, date}`` into a :class:`Withdrawal` (#74).
+    """Parse ``withdrawn: {reason, date, kind?}`` into a :class:`Withdrawal` (#74).
 
-    Both fields are required when the key is present — a decision against a need must say why
-    and when, the same way an attestation needs who and when.
+    ``reason`` and ``date`` are required when the key is present — a decision against a need must
+    say why and when, the same way an attestation needs who and when. ``kind`` is optional and
+    defaults to ``wont_do``; it is validated with the same ``Enum(name) except ValueError`` pattern
+    as ``SourceKind``, so an unknown kind is a :class:`LoaderError` the author owns.
     """
     if raw is None:
         return None
@@ -142,7 +145,13 @@ def _withdrawal(raw: object, where: str) -> Withdrawal | None:
     date = _opt_str(tbl.get("date"), f"{where}.date")
     if not reason or not date:
         raise LoaderError(f"{where}: a withdrawal needs both 'reason' and 'date'")
-    return Withdrawal(reason=reason, date=date)
+    kind_name = _opt_str(tbl.get("kind"), f"{where}.kind") or WithdrawalKind.WONT_DO.value
+    try:
+        kind = WithdrawalKind(kind_name)
+    except ValueError:
+        kinds = "|".join(k.value for k in WithdrawalKind)
+        raise LoaderError(f"{where}.kind: unknown withdrawal kind {kind_name!r} ({kinds})") from None
+    return Withdrawal(reason=reason, date=date, kind=kind)
 
 
 # Old source-kind names (pre-0.3.58) mapped to the primary/secondary/assumption ladder, so

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/model.py

@@ -161,17 +161,33 @@ class Attestation:
     comment: str | None = None  # the review's feedback / rationale, kept on the record
 
 
+class WithdrawalKind(StrEnum):
+    """Why a need is off the board — the decision's *kind*, as data, not only free-text reason.
+
+    All three take the need off the active board and out of coverage identically; the kind records
+    *why* so the board can tell a validated-but-off-strategy need apart from one killed as not
+    worth doing. ``OUT_OF_SCOPE`` is the case a real, client-evidenced need is declined because it
+    is not the product being built — distinct from ``WONT_DO`` (decided against on its merits) and
+    ``DUPLICATE`` (the same want is tracked under another need).
+    """
+
+    WONT_DO = "wont_do"  # decided against on its merits — the default, #74's original meaning
+    OUT_OF_SCOPE = "out_of_scope"  # real and valid, but not this product
+    DUPLICATE = "duplicate"  # the same want is tracked elsewhere
+
+
 @dataclass(frozen=True)
 class Withdrawal:
     """A decision not to pursue a need — withdrawn / won't-do (#74).
 
     Unlike a draft (staged, not yet decided), a withdrawal is a decision *against*: the need is
-    taken off the active board and out of coverage, with its ``reason`` and ``date`` kept on the
-    record as the durable trace (``prodc show`` still renders it). Reinstate to put it back.
+    taken off the active board and out of coverage, with its ``reason``, ``date`` and ``kind`` kept
+    on the record as the durable trace (``prodc show`` still renders it). Reinstate to put it back.
     """
 
     reason: str
     date: str
+    kind: WithdrawalKind = WithdrawalKind.WONT_DO
 
 
 @dataclass(frozen=True)

{prodc-0.3.76 → prodc-0.3.77}/src/prodc/writer.py

@@ -474,16 +474,21 @@ def withdraw(
     *,
     reason: str,
     date: str,
+    kind: str = "wont_do",
     expect_sha: str | None,
     dry_run: bool,
 ) -> Edit:
     """Record a decision against a need — withdrawn / won't-do (#74).
 
-    Writes a ``withdrawn: {reason, date}`` mapping onto the need, which takes it off the active
-    board and out of coverage; the record stays as its durable trace. Replaces any existing
-    withdrawal (re-withdrawing updates the reason/date). Reinstate with :func:`reinstate`.
+    Writes a ``withdrawn: {reason, date, kind?}`` mapping onto the need, which takes it off the
+    active board and out of coverage; the record stays as its durable trace. ``kind`` says *why*
+    (``wont_do`` default, ``out_of_scope``, ``duplicate``) and is written only when it is not the
+    default, to keep the common case clean. Replaces any existing withdrawal (re-withdrawing
+    updates it). Reinstate with :func:`reinstate`.
     """
     mark: dict[str, object] = {"reason": reason, "date": date}
+    if kind != "wont_do":
+        mark["kind"] = kind
     path, _ = _locate(config, need_id)
     doc, old_text = _read_doc(path)
     if expect_sha is not None and _sha256(old_text) != expect_sha:

{prodc-0.3.76 → prodc-0.3.77}/tests/test_withdrawn.py

@@ -242,7 +242,11 @@ def test_show_json_carries_withdrawn(tmp_path: Path, capsys: pytest.CaptureFixtu
 
     main(["show", "W-1", "--config", str(_project(tmp_path)), "--json"])
     payload = json.loads(capsys.readouterr().out)
-    assert payload["withdrawn"] == {"reason": "superseded by N-1", "date": "2026-10-10"}
+    assert payload["withdrawn"] == {
+        "reason": "superseded by N-1",
+        "date": "2026-10-10",
+        "kind": "wont_do",  # default when the YAML omits kind
+    }
 
 
 def test_status_json_live_need_has_null_withdrawn(
@@ -254,3 +258,85 @@ def test_status_json_live_need_has_null_withdrawn(
     payload = json.loads(capsys.readouterr().out)
     n1 = next(n for n in payload["needs"] if n["id"] == "N-1")
     assert n1["withdrawn"] is None
+
+
+# --- withdrawal kind (#74 follow-up) ----------------------------------------
+
+_KIND_NEEDS = """
+needs:
+  - id: N-1
+    text: user can see a delivered thing
+    proofs: ["x:1"]
+  - id: OOS-1
+    text: a real but off-strategy need
+    withdrawn:
+      reason: not the product we build
+      date: 2026-10-10
+      kind: out_of_scope
+"""
+
+
+def test_loader_parses_withdrawal_kind(tmp_path: Path) -> None:
+    from prodc.model import WithdrawalKind
+
+    cfg = Config.load(_project(tmp_path, needs=_KIND_NEEDS))
+    by_id = {n.id: n for n in load(cfg).needs}
+    assert by_id["OOS-1"].withdrawn is not None
+    assert by_id["OOS-1"].withdrawn.kind is WithdrawalKind.OUT_OF_SCOPE
+
+
+def test_withdrawal_kind_defaults_wont_do(tmp_path: Path) -> None:
+    from prodc.model import WithdrawalKind
+
+    cfg = Config.load(_project(tmp_path))  # W-1 omits kind
+    by_id = {n.id: n for n in load(cfg).needs}
+    w = by_id["W-1"].withdrawn
+    assert w is not None and w.kind is WithdrawalKind.WONT_DO
+
+
+def test_unknown_withdrawal_kind_rejected(tmp_path: Path) -> None:
+    needs = _KIND_NEEDS.replace("kind: out_of_scope", "kind: bogus")
+    with pytest.raises(LoaderError, match="unknown withdrawal kind 'bogus'"):
+        load(Config.load(_project(tmp_path, needs=needs)))
+
+
+def test_withdraw_writes_non_default_kind(tmp_path: Path) -> None:
+    from prodc.cli import main
+    from prodc.model import WithdrawalKind
+
+    cfg = _project(tmp_path)
+    code = main(
+        ["withdraw", "N-1", "--reason", "off strategy", "--kind", "out_of_scope",
+         "--date", "2026-10-15", "--config", str(cfg)]
+    )
+    assert code == 0
+    by_id = {n.id: n for n in load(Config.load(cfg)).needs}
+    w = by_id["N-1"].withdrawn
+    assert w is not None and w.kind is WithdrawalKind.OUT_OF_SCOPE
+
+
+def test_withdraw_omits_default_kind_in_yaml(tmp_path: Path) -> None:
+    from prodc.cli import main
+
+    cfg = _project(tmp_path)
+    main(["withdraw", "N-1", "--reason", "nope", "--date", "2026-10-15", "--config", str(cfg)])
+    text = (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
+    assert "kind:" not in text  # wont_do is the default; not written, keeps files clean
+
+
+def test_status_breaks_down_withdrawn_by_kind(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    main(["status", "--config", str(_project(tmp_path, needs=_KIND_NEEDS))])
+    out = capsys.readouterr().out
+    assert "withdrawn: 1 (decided against) — 1 out_of_scope" in out
+
+
+def test_show_tags_non_default_kind(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    main(["show", "OOS-1", "--config", str(_project(tmp_path, needs=_KIND_NEEDS))])
+    out = capsys.readouterr().out
+    assert "withdrawn [out_of_scope]: not the product we build (2026-10-10)" in out