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.
- {prodc-0.3.65 → prodc-0.3.66}/PKG-INFO +1 -1
- {prodc-0.3.65 → prodc-0.3.66}/pyproject.toml +1 -1
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/agent.md +1 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/board.py +10 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/app.py +40 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/commands.py +48 -1
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/render.py +2 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/loader.py +19 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/model.py +41 -14
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/report.py +8 -3
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/report_html.py +5 -1
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/writer.py +47 -0
- prodc-0.3.66/tests/test_withdrawn.py +256 -0
- {prodc-0.3.65 → prodc-0.3.66}/.gitignore +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/CHANGELOG.md +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/LICENSE +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/README.md +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/examples/quickstart/features/orders.feature +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/examples/quickstart/needs/jordan.yaml +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/examples/quickstart/prodc.toml +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/__init__.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/adapters.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/callbacks.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/__init__.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/common.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/cli/serialize.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/config.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/dedup.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/py.typed +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/src/prodc/status.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_adapters.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_callbacks.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_cli.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_command_hook.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_dedup.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_description.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_drafts.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_external_adapter.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_gitlab_source.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_importance.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_loader.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_models.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_report.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_report_html.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_roles.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_sources.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_staleness.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_status.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_suggest.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_variants.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_who_variants.py +0 -0
- {prodc-0.3.65 → prodc-0.3.66}/tests/test_writer.py +0 -0
- {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.
|
|
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
|
|
@@ -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
|
|
203
|
-
counting it too would double-count (#43); a non-product need
|
|
204
|
-
excluded from product coverage (#48)
|
|
205
|
-
|
|
206
|
-
|
|
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: ``"
|
|
215
|
-
(staged, not yet promoted, #60) and ``"nonproduct"``
|
|
216
|
-
|
|
217
|
-
|
|
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
|
|
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
|
-
|
|
230
|
-
|
|
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
|
-
|
|
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
|
|
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": [
|
|
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
|
|
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
|