prodc 0.3.65__tar.gz → 0.3.66__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. {prodc-0.3.65 → prodc-0.3.66}/PKG-INFO +1 -1
  2. {prodc-0.3.65 → prodc-0.3.66}/pyproject.toml +1 -1
  3. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/agent.md +1 -0
  4. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/board.py +10 -0
  5. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/app.py +40 -0
  6. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/commands.py +48 -1
  7. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/render.py +2 -0
  8. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/loader.py +19 -0
  9. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/model.py +41 -14
  10. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/report.py +8 -3
  11. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/report_html.py +5 -1
  12. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/writer.py +47 -0
  13. prodc-0.3.66/tests/test_withdrawn.py +256 -0
  14. {prodc-0.3.65 → prodc-0.3.66}/.gitignore +0 -0
  15. {prodc-0.3.65 → prodc-0.3.66}/CHANGELOG.md +0 -0
  16. {prodc-0.3.65 → prodc-0.3.66}/LICENSE +0 -0
  17. {prodc-0.3.65 → prodc-0.3.66}/README.md +0 -0
  18. {prodc-0.3.65 → prodc-0.3.66}/examples/quickstart/features/orders.feature +0 -0
  19. {prodc-0.3.65 → prodc-0.3.66}/examples/quickstart/needs/jordan.yaml +0 -0
  20. {prodc-0.3.65 → prodc-0.3.66}/examples/quickstart/prodc.toml +0 -0
  21. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/__init__.py +0 -0
  22. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/adapters.py +0 -0
  23. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/callbacks.py +0 -0
  24. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/__init__.py +0 -0
  25. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/common.py +0 -0
  26. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/serialize.py +0 -0
  27. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/config.py +0 -0
  28. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/dedup.py +0 -0
  29. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/py.typed +0 -0
  30. {prodc-0.3.65 → prodc-0.3.66}/src/prodc/status.py +0 -0
  31. {prodc-0.3.65 → prodc-0.3.66}/tests/test_adapters.py +0 -0
  32. {prodc-0.3.65 → prodc-0.3.66}/tests/test_callbacks.py +0 -0
  33. {prodc-0.3.65 → prodc-0.3.66}/tests/test_cli.py +0 -0
  34. {prodc-0.3.65 → prodc-0.3.66}/tests/test_command_hook.py +0 -0
  35. {prodc-0.3.65 → prodc-0.3.66}/tests/test_dedup.py +0 -0
  36. {prodc-0.3.65 → prodc-0.3.66}/tests/test_description.py +0 -0
  37. {prodc-0.3.65 → prodc-0.3.66}/tests/test_drafts.py +0 -0
  38. {prodc-0.3.65 → prodc-0.3.66}/tests/test_external_adapter.py +0 -0
  39. {prodc-0.3.65 → prodc-0.3.66}/tests/test_gitlab_source.py +0 -0
  40. {prodc-0.3.65 → prodc-0.3.66}/tests/test_importance.py +0 -0
  41. {prodc-0.3.65 → prodc-0.3.66}/tests/test_loader.py +0 -0
  42. {prodc-0.3.65 → prodc-0.3.66}/tests/test_models.py +0 -0
  43. {prodc-0.3.65 → prodc-0.3.66}/tests/test_report.py +0 -0
  44. {prodc-0.3.65 → prodc-0.3.66}/tests/test_report_html.py +0 -0
  45. {prodc-0.3.65 → prodc-0.3.66}/tests/test_roles.py +0 -0
  46. {prodc-0.3.65 → prodc-0.3.66}/tests/test_sources.py +0 -0
  47. {prodc-0.3.65 → prodc-0.3.66}/tests/test_staleness.py +0 -0
  48. {prodc-0.3.65 → prodc-0.3.66}/tests/test_status.py +0 -0
  49. {prodc-0.3.65 → prodc-0.3.66}/tests/test_suggest.py +0 -0
  50. {prodc-0.3.65 → prodc-0.3.66}/tests/test_variants.py +0 -0
  51. {prodc-0.3.65 → prodc-0.3.66}/tests/test_who_variants.py +0 -0
  52. {prodc-0.3.65 → prodc-0.3.66}/tests/test_writer.py +0 -0
  53. {prodc-0.3.65 → prodc-0.3.66}/tests/test_writer_comments.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: prodc
3
- Version: 0.3.65
3
+ Version: 0.3.66
4
4
  Summary: Product management as code: roles, flows, and features traced to evidence.
5
5
  Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
6
6
  Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "prodc"
3
- version = "0.3.65"
3
+ version = "0.3.66"
4
4
  description = "Product management as code: roles, flows, and features traced to evidence."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.12"
@@ -75,6 +75,7 @@ Read first, then act, then check.
75
75
  | link a recurring want to a shared baseline | `prodc recurrence --suggest --apply --baseline-id <id> --file needs/<f>.yaml` |
76
76
  | record a human/AI review of the warrant | `prodc attest <id> --by <who> --date <ISO> [--ai]` |
77
77
  | record a human acceptance pass | `prodc accept <id> --who <person> --date <ISO>` |
78
+ | decide against a need (won't-do) | `prodc withdraw <id> --reason "…"` — off the board + out of coverage; `prodc reinstate <id>` puts it back |
78
79
  | hand a human a readable status file | `prodc report -o status.md` (markdown; `--format html` for an interactive viewer; `--client ID` to scope) |
79
80
  | 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) |
80
81
  | gate in CI | `prodc lint --strict` |
@@ -97,6 +97,11 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
97
97
  "goal": need.goal,
98
98
  "release": need.release,
99
99
  "claim": need.claim,
100
+ "withdrawn": (
101
+ {"reason": need.withdrawn.reason, "date": need.withdrawn.date}
102
+ if need.withdrawn
103
+ else None
104
+ ),
100
105
  "proofs": list(need.proofs),
101
106
  "detail": list(r.detail),
102
107
  "warnings": list(r.warnings),
@@ -138,6 +143,11 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
138
143
  "release": need.release,
139
144
  "product": need.product,
140
145
  "draft": need.draft,
146
+ "withdrawn": (
147
+ {"reason": need.withdrawn.reason, "date": need.withdrawn.date}
148
+ if need.withdrawn
149
+ else None
150
+ ),
141
151
  "importance": need.importance,
142
152
  "importance_set_at": need.importance_set_at,
143
153
  "claim": need.claim,
@@ -26,12 +26,14 @@ from .commands import (
26
26
  cmd_plan,
27
27
  cmd_portfolio,
28
28
  cmd_recurrence,
29
+ cmd_reinstate,
29
30
  cmd_report,
30
31
  cmd_set,
31
32
  cmd_show,
32
33
  cmd_status,
33
34
  cmd_suggest,
34
35
  cmd_sync,
36
+ cmd_withdraw,
35
37
  )
36
38
 
37
39
 
@@ -284,6 +286,44 @@ def main(argv: list[str] | None = None) -> int:
284
286
  )
285
287
  ac.set_defaults(func=cmd_accept)
286
288
 
289
+ wd = sub.add_parser(
290
+ "withdraw", help="record a decision against a need — withdrawn / won't-do (#74)"
291
+ )
292
+ wd.add_argument("need_id", help="the need id to withdraw")
293
+ wd.add_argument(
294
+ "--reason", required=True, help="why it was decided against (kept on the record)"
295
+ )
296
+ wd.add_argument("--date", default=None, help="when (ISO, e.g. 2026-10-10; default: today)")
297
+ wd.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
298
+ wd.add_argument("--json", action="store_true", help="machine-readable output")
299
+ wd.add_argument(
300
+ "--dry-run", action="store_true", help="validate and show the diff, don't write"
301
+ )
302
+ wd.add_argument(
303
+ "--expect-sha",
304
+ default=None,
305
+ metavar="SHA256",
306
+ help="refuse if the file's content hash differs (optimistic lock)",
307
+ )
308
+ wd.set_defaults(func=cmd_withdraw)
309
+
310
+ ri = sub.add_parser(
311
+ "reinstate", help="remove a need's withdrawal, putting it back on the board (#74)"
312
+ )
313
+ ri.add_argument("need_id", help="the need id to reinstate")
314
+ ri.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
315
+ ri.add_argument("--json", action="store_true", help="machine-readable output")
316
+ ri.add_argument(
317
+ "--dry-run", action="store_true", help="validate and show the diff, don't write"
318
+ )
319
+ ri.add_argument(
320
+ "--expect-sha",
321
+ default=None,
322
+ metavar="SHA256",
323
+ help="refuse if the file's content hash differs (optimistic lock)",
324
+ )
325
+ ri.set_defaults(func=cmd_reinstate)
326
+
287
327
  pf = sub.add_parser("portfolio", help="roll up many repos into one scoreboard")
288
328
  pf.add_argument("configs", nargs="+", metavar="PRODC_TOML", help="one or more prodc.toml paths")
289
329
  pf.add_argument("--json", action="store_true", help="machine-readable output")
@@ -51,8 +51,10 @@ from ..writer import (
51
51
  attest,
52
52
  capture_source,
53
53
  link_variant_group,
54
+ reinstate,
54
55
  set_field,
55
56
  set_importance,
57
+ withdraw,
56
58
  )
57
59
  from .common import RepoRow, emit_edit, exit_code, git_rev, load_or_report
58
60
  from .render import (
@@ -204,7 +206,8 @@ def cmd_status(args: argparse.Namespace) -> int:
204
206
  needs = list(model.needs)
205
207
  # Draft needs (#60) are staged: kept off the counted board (and coverage, recurrence,
206
208
  # orphans) until promoted with `set <id> draft=false`, unless --include-drafts is passed.
207
- draft_count = sum(1 for n in needs if n.draft)
209
+ draft_count = sum(1 for n in needs if n.draft and not n.is_withdrawn)
210
+ withdrawn_count = sum(1 for n in needs if n.is_withdrawn)
208
211
  needs = board_needs(needs, include_drafts=args.include_drafts)
209
212
  # Scoped coverage (#49): restrict the board + coverage to a subset, so the number people
210
213
  # act on (this client, this goal) isn't diluted by the whole mixed board.
@@ -259,6 +262,8 @@ def cmd_status(args: argparse.Namespace) -> int:
259
262
  print(summary_line(summary))
260
263
  if draft_count and not args.include_drafts:
261
264
  print(f"drafts: {draft_count} staged (hidden — --include-drafts to show) (#60)")
265
+ if withdrawn_count:
266
+ print(f"withdrawn: {withdrawn_count} (decided against) (#74)")
262
267
  visible = [r for r in results if r.need.product]
263
268
  if args.only_must:
264
269
  visible = [r for r in visible if r.need.must]
@@ -476,6 +481,48 @@ def cmd_accept(args: argparse.Namespace) -> int:
476
481
  return emit_edit(edit, args.dry_run, args.json)
477
482
 
478
483
 
484
+ def cmd_withdraw(args: argparse.Namespace) -> int:
485
+ """Record a decision against a need — withdrawn / won't-do (#74)."""
486
+ cfg_path = Path(args.config)
487
+ if not cfg_path.exists():
488
+ print(f"prodc: no config at {cfg_path}", file=sys.stderr)
489
+ return 2
490
+ try:
491
+ cfg = Config.load(cfg_path)
492
+ edit = withdraw(
493
+ cfg,
494
+ args.need_id,
495
+ reason=args.reason,
496
+ date=args.date or date.today().isoformat(),
497
+ expect_sha=args.expect_sha,
498
+ dry_run=args.dry_run,
499
+ )
500
+ except (ConfigError, WriteError) as exc:
501
+ print(f"prodc: {exc}", file=sys.stderr)
502
+ return 2
503
+ return emit_edit(edit, args.dry_run, args.json)
504
+
505
+
506
+ def cmd_reinstate(args: argparse.Namespace) -> int:
507
+ """Remove a need's withdrawal, putting it back on the active board (#74)."""
508
+ cfg_path = Path(args.config)
509
+ if not cfg_path.exists():
510
+ print(f"prodc: no config at {cfg_path}", file=sys.stderr)
511
+ return 2
512
+ try:
513
+ cfg = Config.load(cfg_path)
514
+ edit = reinstate(
515
+ cfg,
516
+ args.need_id,
517
+ expect_sha=args.expect_sha,
518
+ dry_run=args.dry_run,
519
+ )
520
+ except (ConfigError, WriteError) as exc:
521
+ print(f"prodc: {exc}", file=sys.stderr)
522
+ return 2
523
+ return emit_edit(edit, args.dry_run, args.json)
524
+
525
+
479
526
  def cmd_capture(args: argparse.Namespace) -> int:
480
527
  """Append a Source to an existing need (capture evidence)."""
481
528
  cfg_path = Path(args.config)
@@ -273,6 +273,8 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
273
273
  f" grounds: {_LABEL[r.state]}{nm} warrant: {_warrant(need)}",
274
274
  f" shape: {ears_shape(need.text).value}",
275
275
  ]
276
+ if need.withdrawn:
277
+ lines.append(f" withdrawn: {need.withdrawn.reason} ({need.withdrawn.date})")
276
278
  if need.description:
277
279
  lines.append(f" description: {need.description}")
278
280
  if need.importance is not None:
@@ -28,6 +28,7 @@ from .model import (
28
28
  Role,
29
29
  Source,
30
30
  SourceKind,
31
+ Withdrawal,
31
32
  )
32
33
 
33
34
 
@@ -104,6 +105,22 @@ def _attestation(raw: object, where: str) -> Attestation | None:
104
105
  )
105
106
 
106
107
 
108
+ def _withdrawal(raw: object, where: str) -> Withdrawal | None:
109
+ """Parse ``withdrawn: {reason, date}`` into a :class:`Withdrawal` (#74).
110
+
111
+ Both fields are required when the key is present — a decision against a need must say why
112
+ and when, the same way an attestation needs who and when.
113
+ """
114
+ if raw is None:
115
+ return None
116
+ tbl = _as_mapping(raw, where)
117
+ reason = _opt_str(tbl.get("reason"), f"{where}.reason")
118
+ date = _opt_str(tbl.get("date"), f"{where}.date")
119
+ if not reason or not date:
120
+ raise LoaderError(f"{where}: a withdrawal needs both 'reason' and 'date'")
121
+ return Withdrawal(reason=reason, date=date)
122
+
123
+
107
124
  # Old source-kind names (pre-0.3.58) mapped to the primary/secondary/assumption ladder, so
108
125
  # existing need files keep loading. `interview` was live user contact (primary); `artifact` was a
109
126
  # cited document (secondary); `proxy`/`internal` were both unevidenced guesses (assumption).
@@ -160,6 +177,7 @@ def _need(
160
177
  release = _opt_str(tbl.get("release"), f"{where}.release")
161
178
  product = _as_bool(tbl["product"], f"{where}.product") if "product" in tbl else True
162
179
  draft = _as_bool(tbl["draft"], f"{where}.draft") if "draft" in tbl else False
180
+ withdrawn = _withdrawal(tbl.get("withdrawn"), f"{where}.withdrawn")
163
181
 
164
182
  sources = tuple(
165
183
  _source(s, f"{where}.sources[{i}]")
@@ -217,6 +235,7 @@ def _need(
217
235
  not_variant_of=not_variant_of,
218
236
  importance_set_at=importance_set_at,
219
237
  draft=draft,
238
+ withdrawn=withdrawn,
220
239
  )
221
240
 
222
241
 
@@ -140,6 +140,19 @@ class Attestation:
140
140
  comment: str | None = None # the review's feedback / rationale, kept on the record
141
141
 
142
142
 
143
+ @dataclass(frozen=True)
144
+ class Withdrawal:
145
+ """A decision not to pursue a need — withdrawn / won't-do (#74).
146
+
147
+ Unlike a draft (staged, not yet decided), a withdrawal is a decision *against*: the need is
148
+ taken off the active board and out of coverage, with its ``reason`` and ``date`` kept on the
149
+ record as the durable trace (``prodc show`` still renders it). Reinstate to put it back.
150
+ """
151
+
152
+ reason: str
153
+ date: str
154
+
155
+
143
156
  @dataclass(frozen=True)
144
157
  class Need:
145
158
  """What a named person wants, with its provenance and its proofs."""
@@ -165,6 +178,7 @@ class Need:
165
178
  release: str | None = None # id of the Release slice this need ships in; None = unslotted
166
179
  product: bool = True # False = infra/NFR/internal, excluded from product coverage (#48)
167
180
  draft: bool = False # True = staged, not yet counted on the board until promoted (#60)
181
+ withdrawn: Withdrawal | None = None # a decision against this need — off the board (#74)
168
182
  not_duplicate_of: tuple[str, ...] = () # ids this need is confirmed NOT a duplicate of (#55)
169
183
  not_variant_of: tuple[str, ...] = () # ids this need is confirmed NOT a shared variant of (#56)
170
184
 
@@ -194,28 +208,37 @@ class Need:
194
208
  kinds = {s.kind for s in self.sources}
195
209
  return next((k for k in order if k in kinds), None)
196
210
 
211
+ @property
212
+ def is_withdrawn(self) -> bool:
213
+ """A decision has been recorded against this need — withdrawn / won't-do (#74)."""
214
+ return self.withdrawn is not None
215
+
197
216
  @property
198
217
  def counts_toward_coverage(self) -> bool:
199
218
  """Whether this need is a unit of product coverage — what :func:`~prodc.status.summarize`
200
219
  counts.
201
220
 
202
- A leaf product need. A flow (a need with ``children``) is a roll-up of its leaves, so
203
- counting it too would double-count (#43); a non-product need (infra/NFR/internal) is
204
- excluded from product coverage (#48). Draft staging is a separate, upstream filter
205
- (:func:`board_needs`), not part of this rule — so a draft still counts once promoted onto
206
- the board (e.g. under ``--include-drafts``).
221
+ A leaf product need that has not been withdrawn. A flow (a need with ``children``) is a
222
+ roll-up of its leaves, so counting it too would double-count (#43); a non-product need
223
+ (infra/NFR/internal) is excluded from product coverage (#48); a withdrawn need is a
224
+ decision against, so it is out of coverage entirely (#74). Draft staging is a separate,
225
+ upstream filter (:func:`board_needs`), not part of this rule — so a draft still counts
226
+ once promoted onto the board (e.g. under ``--include-drafts``).
207
227
  """
208
- return not self.children and self.product
228
+ return not self.children and self.product and not self.is_withdrawn
209
229
 
210
230
  @property
211
231
  def excluded_reason(self) -> str | None:
212
232
  """Why this need is off the counted board, or ``None`` when it is on it.
213
233
 
214
- The single home for the lifecycle exclusions, so a new state lands here once: ``"draft"``
215
- (staged, not yet promoted, #60) and ``"nonproduct"`` (infra/NFR/internal, #48). A flow is
216
- not excluded — it is a roll-up row on the board — so ``children`` is not a reason here
217
- (that axis is :attr:`counts_toward_coverage`).
234
+ The single home for the lifecycle exclusions, so a new state lands here once: ``"withdrawn"``
235
+ (a decision against, #74), ``"draft"`` (staged, not yet promoted, #60), and ``"nonproduct"``
236
+ (infra/NFR/internal, #48). Withdrawal is checked first — a decision against overrides
237
+ staging or scope. A flow is not excluded — it is a roll-up row on the board — so
238
+ ``children`` is not a reason here (that axis is :attr:`counts_toward_coverage`).
218
239
  """
240
+ if self.is_withdrawn:
241
+ return "withdrawn"
219
242
  if self.draft:
220
243
  return "draft"
221
244
  if not self.product:
@@ -224,12 +247,16 @@ class Need:
224
247
 
225
248
 
226
249
  def board_needs(needs: list[Need], *, include_drafts: bool) -> list[Need]:
227
- """The needs on the counted board: a draft (#60) is staged off it until promoted.
250
+ """The needs on the active board: a withdrawn need (#74) is always off it, and a draft (#60)
251
+ is staged off until promoted.
228
252
 
229
- ``include_drafts`` keeps them on (the ``--include-drafts`` flag). The one place the
230
- draft-staging rule lives, shared by ``status`` and ``plan`` so the two never diverge.
253
+ A withdrawn need is a decision against, so it is dropped unconditionally — there is no
254
+ ``--include`` flag for it (its durable trace is the YAML record and ``prodc show``). Drafts
255
+ are kept when ``include_drafts`` (the ``--include-drafts`` flag). The one place the
256
+ board-membership rule lives, shared by ``status`` and ``plan`` so the two never diverge.
231
257
  """
232
- return list(needs) if include_drafts else [n for n in needs if not n.draft]
258
+ kept = [n for n in needs if not n.is_withdrawn]
259
+ return kept if include_drafts else [n for n in kept if not n.draft]
233
260
 
234
261
 
235
262
  class ArgKind(StrEnum):
@@ -75,10 +75,11 @@ def render_markdown(
75
75
  "proves yet — not a failure.",
76
76
  ]
77
77
 
78
- # Needs grouped by who, like the board.
78
+ # Needs grouped by who, like the board. A withdrawn need (#74) is off the active board, so
79
+ # it is dropped here (its trace is the YAML record and `prodc show`), never shown as a gap.
79
80
  groups: dict[str, list[NeedResult]] = {}
80
81
  for r in results:
81
- if not r.need.product:
82
+ if not r.need.product or r.need.is_withdrawn:
82
83
  continue
83
84
  groups.setdefault(r.need.who or "(unassigned)", []).append(r)
84
85
  if groups:
@@ -153,7 +154,11 @@ def render_markdown(
153
154
 
154
155
  # Open questions: the brief — opinions (no evidence) or HOLEs (no proof), must-haves first.
155
156
  open_ = [
156
- r for r in results if r.need.product and (r.need.is_opinion or r.state is NeedState.HOLE)
157
+ r
158
+ for r in results
159
+ if r.need.product
160
+ and not r.need.is_withdrawn
161
+ and (r.need.is_opinion or r.state is NeedState.HOLE)
157
162
  ]
158
163
  open_.sort(key=lambda r: (not r.need.must, r.need.id))
159
164
  out += ["## Open questions", ""]
@@ -49,7 +49,11 @@ def board_payload(
49
49
  "opinion": summary.opinion,
50
50
  "coverage_pct": round(summary.coverage * 100),
51
51
  },
52
- "needs": [need_payload(r, flavor="html") for r in results if r.need.product],
52
+ "needs": [
53
+ need_payload(r, flavor="html")
54
+ for r in results
55
+ if r.need.product and not r.need.is_withdrawn
56
+ ],
53
57
  "goals": [{"id": g.id, "text": g.text, **_cov(s.delivered, s.total)} for g, s in goal_cov],
54
58
  "ungoaled": [r.need.id for r in ungoaled],
55
59
  "releases": [
@@ -429,6 +429,53 @@ def attest(
429
429
  return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
430
430
 
431
431
 
432
+ def withdraw(
433
+ config: Config,
434
+ need_id: str,
435
+ *,
436
+ reason: str,
437
+ date: str,
438
+ expect_sha: str | None,
439
+ dry_run: bool,
440
+ ) -> Edit:
441
+ """Record a decision against a need — withdrawn / won't-do (#74).
442
+
443
+ Writes a ``withdrawn: {reason, date}`` mapping onto the need, which takes it off the active
444
+ board and out of coverage; the record stays as its durable trace. Replaces any existing
445
+ withdrawal (re-withdrawing updates the reason/date). Reinstate with :func:`reinstate`.
446
+ """
447
+ mark: dict[str, object] = {"reason": reason, "date": date}
448
+ path, _ = _locate(config, need_id)
449
+ doc, old_text = _read_doc(path)
450
+ if expect_sha is not None and _sha256(old_text) != expect_sha:
451
+ raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
452
+ for raw in _need_list(doc, path):
453
+ if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
454
+ cast("dict[str, object]", raw)["withdrawn"] = mark
455
+ break
456
+ return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
457
+
458
+
459
+ def reinstate(config: Config, need_id: str, *, expect_sha: str | None, dry_run: bool) -> Edit:
460
+ """Remove a need's ``withdrawn`` mark, putting it back on the active board (#74).
461
+
462
+ Errors if the need is not currently withdrawn — reinstating a live need is a mistake worth
463
+ surfacing, not a silent no-op.
464
+ """
465
+ path, _ = _locate(config, need_id)
466
+ doc, old_text = _read_doc(path)
467
+ if expect_sha is not None and _sha256(old_text) != expect_sha:
468
+ raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
469
+ for raw in _need_list(doc, path):
470
+ if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
471
+ need = cast("dict[str, object]", raw)
472
+ if "withdrawn" not in need:
473
+ raise WriteError(f"need {need_id!r} is not withdrawn")
474
+ del need["withdrawn"]
475
+ break
476
+ return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
477
+
478
+
432
479
  def accept(
433
480
  config: Config,
434
481
  need_id: str,
@@ -0,0 +1,256 @@
1
+ """Withdrawn / won't-do need state (#74): a decision against a need takes it off the
2
+ active board and out of coverage, with the YAML record as its durable trace."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ from pathlib import Path
8
+
9
+ import pytest
10
+
11
+ from prodc.config import Config
12
+ from prodc.loader import LoaderError, load
13
+ from prodc.model import Need, Withdrawal
14
+
15
+ _TOML = """
16
+ [prodc]
17
+ needs = ["needs/*.yaml"]
18
+ """
19
+
20
+ _NEEDS = """
21
+ needs:
22
+ - id: N-1
23
+ text: user can see a delivered thing
24
+ proofs: ["x:1"]
25
+ - id: W-1
26
+ text: a need we decided against
27
+ withdrawn:
28
+ reason: superseded by N-1
29
+ date: 2026-10-10
30
+ """
31
+
32
+
33
+ def _project(tmp_path: Path, toml: str = _TOML, needs: str = _NEEDS) -> Path:
34
+ (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
35
+ (tmp_path / "prodc.toml").write_text(toml, encoding="utf-8")
36
+ (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
37
+ return tmp_path / "prodc.toml"
38
+
39
+
40
+ # --- model / loader ---------------------------------------------------------
41
+
42
+
43
+ def test_loader_parses_withdrawal(tmp_path: Path) -> None:
44
+ cfg = Config.load(_project(tmp_path))
45
+ by_id = {n.id: n for n in load(cfg).needs}
46
+ w = by_id["W-1"].withdrawn
47
+ assert w == Withdrawal(reason="superseded by N-1", date="2026-10-10")
48
+ assert by_id["W-1"].is_withdrawn is True
49
+ assert by_id["N-1"].is_withdrawn is False
50
+
51
+
52
+ def test_loader_errors_on_missing_field(tmp_path: Path) -> None:
53
+ bad = """
54
+ needs:
55
+ - id: W-2
56
+ text: missing the date
57
+ withdrawn:
58
+ reason: no date given
59
+ """
60
+ with pytest.raises(LoaderError, match="withdrawal needs both 'reason' and 'date'"):
61
+ load(Config.load(_project(tmp_path, needs=bad)))
62
+
63
+
64
+ def test_excluded_reason_precedence() -> None:
65
+ # withdrawn overrides draft and nonproduct
66
+ both = Need(
67
+ id="X", text="t", draft=True, product=False, withdrawn=Withdrawal("done", "2026-01-01")
68
+ )
69
+ assert both.excluded_reason == "withdrawn"
70
+ assert Need(id="X", text="t", draft=True).excluded_reason == "draft"
71
+ assert Need(id="X", text="t", product=False).excluded_reason == "nonproduct"
72
+ assert Need(id="X", text="t").excluded_reason is None
73
+
74
+
75
+ def test_counts_toward_coverage_excludes_withdrawn() -> None:
76
+ live = Need(id="X", text="t")
77
+ gone = Need(id="X", text="t", withdrawn=Withdrawal("no", "2026-01-01"))
78
+ assert live.counts_toward_coverage is True
79
+ assert gone.counts_toward_coverage is False
80
+
81
+
82
+ def test_board_needs_always_excludes_withdrawn() -> None:
83
+ from prodc.model import board_needs
84
+
85
+ live = Need(id="A", text="t")
86
+ gone = Need(id="B", text="t", withdrawn=Withdrawal("no", "2026-01-01"))
87
+ draft = Need(id="C", text="t", draft=True)
88
+ # withdrawn dropped whether or not drafts are included; drafts still gated by the flag
89
+ assert [n.id for n in board_needs([live, gone, draft], include_drafts=False)] == ["A"]
90
+ assert [n.id for n in board_needs([live, gone, draft], include_drafts=True)] == ["A", "C"]
91
+
92
+
93
+ # --- status (board + coverage) ----------------------------------------------
94
+
95
+
96
+ def test_status_excludes_withdrawn_from_board_and_coverage(
97
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
98
+ ) -> None:
99
+ from prodc.cli import main
100
+
101
+ main(["status", "--config", str(_project(tmp_path)), "--json"])
102
+ payload = json.loads(capsys.readouterr().out)
103
+ ids = {n["id"] for n in payload["needs"]}
104
+ assert ids == {"N-1"} # W-1 is off the board
105
+ assert payload["summary"]["total"] == 1 # and out of coverage
106
+
107
+
108
+ def test_status_withdrawn_not_shown_even_with_include_drafts(
109
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
110
+ ) -> None:
111
+ from prodc.cli import main
112
+
113
+ main(["status", "--config", str(_project(tmp_path)), "--include-drafts", "--json"])
114
+ payload = json.loads(capsys.readouterr().out)
115
+ assert {n["id"] for n in payload["needs"]} == {"N-1"} # no --include flag for withdrawn
116
+
117
+
118
+ def test_status_text_shows_withdrawn_count(
119
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
120
+ ) -> None:
121
+ from prodc.cli import main
122
+
123
+ main(["status", "--config", str(_project(tmp_path))])
124
+ out = capsys.readouterr().out
125
+ assert "withdrawn: 1 (decided against) (#74)" in out
126
+
127
+
128
+ def test_coverage_before_and_after_withdraw(
129
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
130
+ ) -> None:
131
+ # two leaves, one delivered, one a HOLE → 1/2 (50%); withdrawing the HOLE → 1/1 (100%)
132
+ needs = """
133
+ needs:
134
+ - id: N-1
135
+ text: delivered thing
136
+ proofs: ["x:1"]
137
+ - id: N-2
138
+ text: an unproven thing
139
+ """
140
+ toml = _TOML + '\n[proofs.x]\nkind = "files"\n'
141
+ (tmp_path / "1").write_text("ok\n", encoding="utf-8") # files adapter root="." → payload "1"
142
+ cfg = _project(tmp_path, toml=toml, needs=needs)
143
+ from prodc.cli import main
144
+
145
+ main(["status", "--config", str(cfg), "--json"])
146
+ before = json.loads(capsys.readouterr().out)["summary"]
147
+ assert (before["delivered"], before["total"]) == (1, 2)
148
+
149
+ main(["withdraw", "N-2", "--reason", "out of scope", "--config", str(cfg)])
150
+ capsys.readouterr() # drop the withdraw diff
151
+ main(["status", "--config", str(cfg), "--json"])
152
+ after = json.loads(capsys.readouterr().out)["summary"]
153
+ assert (after["delivered"], after["total"]) == (1, 1) # HOLE gone from the denominator
154
+
155
+
156
+ # --- writer verbs (withdraw / reinstate) ------------------------------------
157
+
158
+
159
+ def test_withdraw_then_reinstate_round_trip(
160
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
161
+ ) -> None:
162
+ from prodc.cli import main
163
+
164
+ cfg = _project(
165
+ tmp_path, needs='needs:\n - id: N-1\n text: a live need\n proofs: ["x:1"]\n'
166
+ )
167
+ assert (
168
+ main(
169
+ [
170
+ "withdraw",
171
+ "N-1",
172
+ "--reason",
173
+ "won't do",
174
+ "--date",
175
+ "2026-10-10",
176
+ "--config",
177
+ str(cfg),
178
+ ]
179
+ )
180
+ == 0
181
+ )
182
+ capsys.readouterr()
183
+ text = (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
184
+ assert "withdrawn:" in text and "won't do" in text
185
+ by_id = {n.id: n for n in load(Config.load(cfg)).needs}
186
+ assert by_id["N-1"].withdrawn == Withdrawal(reason="won't do", date="2026-10-10")
187
+
188
+ assert main(["reinstate", "N-1", "--config", str(cfg)]) == 0
189
+ capsys.readouterr()
190
+ assert "withdrawn:" not in (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
191
+ assert load(Config.load(cfg)).needs[0].withdrawn is None
192
+
193
+
194
+ def test_withdraw_default_date_is_today(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
195
+ from datetime import date
196
+
197
+ from prodc.cli import main
198
+
199
+ cfg = _project(tmp_path, needs="needs:\n - id: N-1\n text: a live need\n")
200
+ main(["withdraw", "N-1", "--reason", "nope", "--config", str(cfg)])
201
+ capsys.readouterr()
202
+ by_id = {n.id: n for n in load(Config.load(cfg)).needs}
203
+ assert by_id["N-1"].withdrawn is not None
204
+ assert by_id["N-1"].withdrawn.date == date.today().isoformat()
205
+
206
+
207
+ def test_reinstate_on_non_withdrawn_errors(
208
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
209
+ ) -> None:
210
+ from prodc.cli import main
211
+
212
+ cfg = _project(tmp_path, needs="needs:\n - id: N-1\n text: a live need\n")
213
+ code = main(["reinstate", "N-1", "--config", str(cfg)])
214
+ assert code == 2
215
+ assert "not withdrawn" in capsys.readouterr().err
216
+
217
+
218
+ def test_withdraw_dry_run_does_not_write(
219
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
220
+ ) -> None:
221
+ from prodc.cli import main
222
+
223
+ cfg = _project(tmp_path, needs="needs:\n - id: N-1\n text: a live need\n")
224
+ main(["withdraw", "N-1", "--reason", "maybe", "--dry-run", "--config", str(cfg)])
225
+ capsys.readouterr()
226
+ assert "withdrawn:" not in (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
227
+
228
+
229
+ # --- show / json payloads ---------------------------------------------------
230
+
231
+
232
+ def test_show_renders_withdrawn_line(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
233
+ from prodc.cli import main
234
+
235
+ main(["show", "W-1", "--config", str(_project(tmp_path))])
236
+ out = capsys.readouterr().out
237
+ assert "withdrawn: superseded by N-1 (2026-10-10)" in out
238
+
239
+
240
+ def test_show_json_carries_withdrawn(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
241
+ from prodc.cli import main
242
+
243
+ main(["show", "W-1", "--config", str(_project(tmp_path)), "--json"])
244
+ payload = json.loads(capsys.readouterr().out)
245
+ assert payload["withdrawn"] == {"reason": "superseded by N-1", "date": "2026-10-10"}
246
+
247
+
248
+ def test_status_json_live_need_has_null_withdrawn(
249
+ tmp_path: Path, capsys: pytest.CaptureFixture[str]
250
+ ) -> None:
251
+ from prodc.cli import main
252
+
253
+ main(["status", "--config", str(_project(tmp_path)), "--json"])
254
+ payload = json.loads(capsys.readouterr().out)
255
+ n1 = next(n for n in payload["needs"] if n["id"] == "N-1")
256
+ assert n1["withdrawn"] is None
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes