prodc 0.3.73__tar.gz → 0.3.75__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.3.73
+Version: 0.3.75
 Summary: Product management as code: roles, flows, and features traced to evidence.
 Project-URL: Homepage, https://gitlab.com/jorgeecardona/prodc
 Project-URL: Repository, https://gitlab.com/jorgeecardona/prodc

{prodc-0.3.73 → prodc-0.3.75}/pyproject.toml

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

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/agent.md

@@ -49,14 +49,16 @@ Read first, then act, then check.
 3. **When someone describes a want**, decide: is there real evidence? If a user said it, capture
    it as `primary`. If it is your own inference, record it as an `assumption` and let it show as the
    weaker signal it is. Stage anything still half-formed with `add … --draft` — it loads but stays off the
-   counted board until you promote it with `prodc set <id> draft=false`.
+   counted board until you promote it. `prodc review` is the triage surface: it lists the staged
+   drafts with a duplicate score, and `--promote <id>…` / `--promote-all` move them onto the board
+   while `--drop <id>…` deletes the ones that were noise.
 4. **Find the proof.** For a HOLE need, `prodc suggest <id>` ranks candidate proofs from the test
    suite; `prodc suggest <id> --apply` writes the best one (preview with `--dry-run`).
 5. **Check for duplication and recurrence.** `prodc dupes` flags near-duplicate needs;
    `prodc recurrence --suggest` finds the same want across clients that could share one baseline.
 6. **Gate before you hand off.** `prodc lint` is the red gate: it exits non-zero on a BROKEN proof
    or a must-have opinion. `prodc lint --strict` *also* fails on any hygiene warning (shared proofs,
-   unlinked recurrence, stale evidence). When you want a coverage threshold in CI, `prodc status`
+   unlinked recurrence, stale evidence, drafts left staged too long via `[lint].draft_max_age_days`). When you want a coverage threshold in CI, `prodc status`
    carries its own gate flags (`--min-coverage`, `--max-dangling`, `--max-orphans`, `--strict`).
 
 ## The commands you will use most
@@ -68,8 +70,9 @@ Read first, then act, then check.
 | rank the backlog | `prodc plan` |
 | prep a client meeting | `prodc brief <client>` |
 | record a new need (with honest provenance) | `prodc add need <id> --text "…" --who <you> --kind assumption --file needs/<f>.yaml` |
+| triage staged drafts | `prodc review` — list them; `--promote <id>…`/`--promote-all` onto the board, `--drop <id>…` to delete |
 | declare a role (the roster) | `prodc add role <id> --text "…" --file needs/<f>.yaml` |
-| attach evidence after a user said something | `prodc capture <id> --kind primary --who <person> --date <ISO> --quote "…"` |
+| 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#…`) |
 | propose / attach a proof for a HOLE | `prodc suggest <id> [--apply] [--dry-run]` |
 | link a recurring want to a shared baseline | `prodc recurrence --suggest --apply --baseline-id <id> --file needs/<f>.yaml` |

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/board.py

@@ -48,16 +48,19 @@ from .status import (
 def warrant(need: Need) -> str:
     """The warrant column: the strongest source kind, or 'opinion' when there is no source at all.
 
-    A `primary` source names its person (`primary:who`); `secondary`/`assumption` show the kind. A
-    need with any source is shown by that kind even if it is an opinion (only an assumption) — the
-    opinion roll-up lives in the gap counts, this column shows the literal evidence tier.
+    A `primary` source names its person (`primary:who`, and `primary:who (role)` when that person's
+    role is recorded, #52); `secondary`/`assumption` show the kind. A need with any source is shown
+    by that kind even if it is an opinion (only an assumption) — the opinion roll-up lives in the
+    gap counts, this column shows the literal evidence tier.
     """
     strongest = need.strongest_kind  # the one source-strength ranking lives on the model
     if strongest is None:
         return "opinion"
     if strongest is SourceKind.PRIMARY:
-        who = next((s.who for s in need.sources if s.kind is SourceKind.PRIMARY and s.who), None)
-        return f"primary:{who}" if who else "primary"
+        src = next((s for s in need.sources if s.kind is SourceKind.PRIMARY and s.who), None)
+        if src is None:
+            return "primary"
+        return f"primary:{src.who}" + (f" ({src.role})" if src.role else "")
     return strongest.value
 
 
@@ -120,6 +123,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
                 {
                     "kind": s.kind.value,
                     "who": s.who,
+                    "role": s.role,
                     "date": s.date,
                     "quote": s.quote,
                     "locator": s.locator,

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/cli/app.py

@@ -28,6 +28,7 @@ from .commands import (
     cmd_recurrence,
     cmd_reinstate,
     cmd_report,
+    cmd_review,
     cmd_set,
     cmd_show,
     cmd_status,
@@ -224,6 +225,12 @@ def main(argv: list[str] | None = None) -> int:
         "(interview/artifact/proxy/internal accepted as aliases)",
     )
     cp.add_argument("--who", default=None, help="the person the evidence came from")
+    cp.add_argument(
+        "--role",
+        default=None,
+        metavar="ID",
+        help="the declared role the person spoke as (validated against roles:) — whose signal it is (#52)",
+    )
     cp.add_argument("--date", default=None, help="when (ISO, e.g. 2026-10-05)")
     cp.add_argument("--quote", default=None, help="a verbatim quote (for a primary source)")
     cp.add_argument("--locator", default=None, help="a source locator (for a secondary source)")
@@ -324,6 +331,35 @@ def main(argv: list[str] | None = None) -> int:
     )
     ri.set_defaults(func=cmd_reinstate)
 
+    rv = sub.add_parser(
+        "review", help="triage staged drafts: list them, or --promote / --drop a batch (#60)"
+    )
+    rv.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    rv.add_argument("--json", action="store_true", help="machine-readable output")
+    rv.add_argument(
+        "--promote",
+        nargs="+",
+        default=None,
+        metavar="ID",
+        help="promote these drafts onto the board (sets draft=false)",
+    )
+    rv.add_argument(
+        "--promote-all",
+        action="store_true",
+        help="promote every staged draft (except any named in --drop)",
+    )
+    rv.add_argument(
+        "--drop",
+        nargs="+",
+        default=None,
+        metavar="ID",
+        help="delete these drafts outright (a draft, never a real need — withdraw that)",
+    )
+    rv.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diffs, don't write"
+    )
+    rv.set_defaults(func=cmd_review)
+
     pf = sub.add_parser("portfolio", help="roll up many boards into one scoreboard")
     pf.add_argument(
         "configs",

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

@@ -50,6 +50,7 @@ from ..writer import (
     add_role,
     attest,
     capture_source,
+    delete_need,
     link_variant_group,
     reinstate,
     set_field,
@@ -136,6 +137,47 @@ def _annotate_importance_warnings(results: list[NeedResult], cfg: Config) -> Non
                 )
 
 
+def _annotate_draft_age_warnings(results: list[NeedResult], cfg: Config) -> None:
+    """Flag staged drafts older than `[lint].draft_max_age_days`, so a batch can't be forgotten (#60).
+
+    Mirrors the importance-revisit check: a draft with no `draft_added` stamp is flagged undated
+    (it cannot be aged, so it is not silently exempt); a dated draft past the limit is flagged with
+    its age. Only runs when the knob is set.
+    """
+    if cfg.draft_max_age_days is None:
+        return
+    today = date.today()
+    for r in results:
+        if not r.need.draft or r.need.is_withdrawn:
+            continue
+        when = r.need.draft_added
+        if when is None:
+            r.warnings.append("draft with no staged date (`add --draft` stamps one) — #60")
+            continue
+        try:
+            days = (today - date.fromisoformat(when)).days
+        except ValueError:
+            continue
+        if days > cfg.draft_max_age_days:
+            r.warnings.append(
+                f"draft staged {days}d ago (> {cfg.draft_max_age_days}d) — promote or drop (#60)"
+            )
+
+
+def _annotate_label_deprecation(results: list[NeedResult]) -> None:
+    """Nudge needs still carrying the free-text `label` toward role + client (#52, deprecation).
+
+    Since Role (#52) carries the archetype and `client` the org, the per-need `label` is redundant —
+    "design partner, Sincerely" is `role` + `client`. Soft only: `label` is still parsed and still
+    renders; this flags it so a board can migrate off it before it is removed.
+    """
+    for r in results:
+        if r.need.label:
+            r.warnings.append(
+                f"'label' ({r.need.label!r}) is deprecated — express it with role + client (#52)"
+            )
+
+
 def _lint_errors(results: list[NeedResult]) -> list[str]:
     """Hard problems a lint gate fails on: a dangling proof, or a must-have with no evidence."""
     errors: list[str] = []
@@ -184,6 +226,8 @@ def cmd_lint(args: argparse.Namespace) -> int:
                     f"who may name the same person: {whos} (needs {', '.join(v.need_ids)}) — #61"
                 )
     _annotate_importance_warnings(results, cfg)
+    _annotate_draft_age_warnings(results, cfg)
+    _annotate_label_deprecation(results)
     errors = _lint_errors(results)
     warnings = [
         (r.need.id, w) for r in sorted(results, key=lambda x: x.need.id) for w in r.warnings
@@ -531,6 +575,132 @@ def cmd_reinstate(args: argparse.Namespace) -> int:
     return emit_edit(edit, args.dry_run, args.json)
 
 
+def cmd_review(args: argparse.Namespace) -> int:
+    """Triage draft needs: list them with a duplicate score, or --promote / --drop a batch (#60).
+
+    The companion to `add --draft`: drafts pile up staged off the board, and this is the surface
+    that clears them. With no action flag it lists each draft with its provenance and the nearest
+    existing need (a dedup score, reusing #55), so a reviewer can see what is a duplicate before
+    promoting. `--promote` flips `draft=false` (sugar over `set`); `--drop` deletes the draft
+    outright (the #60 delete-need path). Both act only on drafts — a real need is withdrawn, not
+    dropped, so its record survives.
+    """
+    loaded = load_or_report(args)
+    if loaded is None:
+        return 2
+    cfg, model = loaded
+    needs = list(model.needs)
+    drafts = [n for n in needs if n.draft and not n.is_withdrawn]
+    draft_ids = {n.id for n in drafts}
+
+    drop = list(args.drop or [])
+    if args.promote_all:
+        promote = [n.id for n in drafts if n.id not in drop]
+    else:
+        promote = list(args.promote or [])
+
+    unknown = [i for i in (*promote, *drop) if i not in draft_ids]
+    if unknown:
+        print(
+            f"prodc: not a staged draft: {', '.join(unknown)} "
+            "(review acts only on drafts — withdraw a real need instead)",
+            file=sys.stderr,
+        )
+        return 2
+    both = sorted(set(promote) & set(drop))
+    if both:
+        print(f"prodc: {', '.join(both)} named in both --promote and --drop", file=sys.stderr)
+        return 2
+
+    if not promote and not drop:
+        return _review_list(cfg, drafts, needs, args.json)
+    return _review_apply(cfg, promote, drop, args)
+
+
+def _review_list(cfg: Config, drafts: list[Need], needs: list[Need], as_json: bool) -> int:
+    """List the staged drafts with provenance and the nearest existing need (read-only)."""
+    rows: list[dict[str, object]] = []
+    for d in sorted(drafts, key=lambda n: n.id):
+        others = [n for n in needs if n.id != d.id]
+        hits = matches_for(d.text, others, cfg.duplicate_threshold, exclude_id=d.id)
+        dup = {"id": hits[0][0].id, "score": round(hits[0][1], 4)} if hits else None
+        rows.append(
+            {
+                "id": d.id,
+                "text": d.text,
+                "who": d.who,
+                "client": d.client,
+                "sources": [s.kind.value for s in d.sources],
+                "staged": d.draft_added,
+                "duplicate": dup,
+            }
+        )
+    if as_json:
+        print(json.dumps({"drafts": rows}, indent=2))
+        return 0
+    for r in rows:
+        who = f" — {r['who']}" if r["who"] else ""
+        client = f" [{r['client']}]" if r["client"] else ""
+        staged = f" (staged {r['staged']})" if r["staged"] else ""
+        print(f"{r['id']}{who}{client}{staged}: {r['text']}")
+        kinds = cast("list[str]", r["sources"])
+        if kinds:
+            print(f"        sources: {', '.join(kinds)}")
+        dup = cast("dict[str, object] | None", r["duplicate"])
+        if dup is not None:
+            print(f"        possible duplicate of {dup['id']} ({dup['score']:.2f}) — #55")
+    print(f"review: {len(rows)} draft(s) staged")
+    return 0
+
+
+def _review_apply(
+    cfg: Config, promote: list[str], drop: list[str], args: argparse.Namespace
+) -> int:
+    """Promote (`draft=false`) and/or drop (delete) the named drafts, each a validated edit (#60).
+
+    Sequential and independent, like `suggest --apply`: each need is one reload-gated, single-file
+    write applied in id order, and a rejection aborts with a non-zero exit (earlier writes stand).
+    """
+    applied: list[tuple[str, str, Edit]] = []  # (action, need_id, edit)
+    try:
+        for nid in sorted(promote):
+            edit = set_field(cfg, nid, "draft=false", expect_sha=None, dry_run=args.dry_run)
+            applied.append(("promote", nid, edit))
+        for nid in sorted(drop):
+            edit = delete_need(cfg, nid, dry_run=args.dry_run)
+            applied.append(("drop", nid, edit))
+    except WriteError as exc:
+        print(f"prodc: {exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "action": action,
+                        "need": nid,
+                        "file": edit.path.name,
+                        "dry_run": args.dry_run,
+                        "diff": edit.diff,
+                    }
+                    for action, nid, edit in applied
+                ],
+                indent=2,
+            )
+        )
+        return 0
+    for action, nid, edit in applied:
+        verb = "would promote" if action == "promote" else "would drop"
+        if not args.dry_run:
+            verb = "promoted" if action == "promote" else "dropped"
+        print(f"{verb} {nid} in {edit.path.name}")
+        print(edit.diff, end="")
+    n_prom = sum(1 for row in applied if row[0] == "promote")
+    n_drop = len(applied) - n_prom
+    print(f"review: {n_prom} promoted, {n_drop} dropped" + (" (dry-run)" if args.dry_run else ""))
+    return 0
+
+
 def cmd_capture(args: argparse.Namespace) -> int:
     """Append a Source to an existing need (capture evidence)."""
     cfg_path = Path(args.config)
@@ -544,6 +714,7 @@ def cmd_capture(args: argparse.Namespace) -> int:
             args.need_id,
             kind=args.kind,
             who=args.who,
+            role=args.role,
             date=args.date,
             quote=args.quote,
             locator=args.locator,
@@ -573,7 +744,9 @@ def _repo_row(config_path: str) -> RepoRow:
     name = p.parent.name or str(p)
     try:
         cfg = Config.load(p)
-        needs = list(load(cfg).needs)
+        # Drafts (#60) and withdrawn needs (#74) are off the counted board, same as `status`/`plan`,
+        # so a repo's portfolio line never inflates with staged ideas.
+        needs = board_needs(list(load(cfg).needs), include_drafts=False)
     except (ConfigError, LoaderError, OSError) as exc:
         return RepoRow(name, 0, 0, 0, 0, 0.0, {}, error=str(exc))
     results = resolve(needs, cfg.adapters, cfg.source_adapters)

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

@@ -304,7 +304,12 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
             bits = [s.kind.value]
             bits += [
                 f"{k}={v}"
-                for k, v in (("who", s.who), ("date", s.date), ("locator", s.locator))
+                for k, v in (
+                    ("who", s.who),
+                    ("role", s.role),
+                    ("date", s.date),
+                    ("locator", s.locator),
+                )
                 if v
             ]
             line = "    - " + "  ".join(bits)

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/cli/serialize.py

@@ -115,6 +115,7 @@ def show_json(r: NeedResult) -> str:
                 {
                     "kind": s.kind.value,
                     "who": s.who,
+                    "role": s.role,
                     "date": s.date,
                     "quote": s.quote,
                     "locator": s.locator,

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/config.py

@@ -115,6 +115,7 @@ class Config:
         default_factory=dict[int, tuple[str, str]]
     )  # [importance].levels — ordinal → (label, meaning); empty = no rubric declared (#59)
     importance_revisit_days: int | None = None  # [lint].importance_revisit_days (#59)
+    draft_max_age_days: int | None = None  # [lint].draft_max_age_days — flag stale drafts (#60)
     default_draft: bool = False  # [add].default_draft — `add` stages as draft by default (#60)
     callbacks: tuple[Callback, ...] = ()  # [[callbacks.hooks]] — lifecycle callbacks (#71)
     callback_state_file: str = ".prodc/state.json"  # [callbacks].state_file — the state ledger
@@ -269,6 +270,11 @@ class Config:
             not isinstance(revisit, int) or isinstance(revisit, bool) or revisit < 1
         ):
             raise ConfigError("[lint].importance_revisit_days must be a positive integer")
+        draft_max_age = lint_tbl.get("draft_max_age_days")
+        if draft_max_age is not None and (
+            not isinstance(draft_max_age, int) or isinstance(draft_max_age, bool) or draft_max_age < 1
+        ):
+            raise ConfigError("[lint].draft_max_age_days must be a positive integer")
 
         importance_levels: dict[int, tuple[str, str]] = {}
         imp_tbl = _as_dict(raw.get("importance", {}), "[importance]")
@@ -303,6 +309,7 @@ class Config:
             stale_after_days=stale,
             importance_levels=importance_levels,
             importance_revisit_days=revisit,
+            draft_max_age_days=draft_max_age,
             default_draft=default_draft,
             callbacks=callbacks,
             callback_state_file=callback_state_file,

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/loader.py

@@ -169,6 +169,7 @@ def _source(raw: object, where: str) -> Source:
     return Source(
         kind=kind,
         who=_opt_str(tbl.get("who"), f"{where}.who"),
+        role=_opt_str(tbl.get("role"), f"{where}.role"),
         date=_opt_str(tbl.get("date"), f"{where}.date"),
         quote=_opt_str(tbl.get("quote"), f"{where}.quote"),
         locator=_opt_str(tbl.get("locator"), f"{where}.locator"),
@@ -201,6 +202,7 @@ def _need(
     release = _opt_str(tbl.get("release"), f"{where}.release")
     product = _as_bool(tbl["product"], f"{where}.product") if "product" in tbl else True
     draft = _as_bool(tbl["draft"], f"{where}.draft") if "draft" in tbl else False
+    draft_added = _opt_str(tbl.get("draft_added"), f"{where}.draft_added")
     withdrawn = _withdrawal(tbl.get("withdrawn"), f"{where}.withdrawn")
     answer = _answer(tbl.get("answer"), f"{where}.answer")
 
@@ -260,6 +262,7 @@ def _need(
         not_variant_of=not_variant_of,
         importance_set_at=importance_set_at,
         draft=draft,
+        draft_added=draft_added,
         withdrawn=withdrawn,
         answer=answer,
     )
@@ -399,6 +402,7 @@ def load(config: Config) -> Model:
     _check_ref(acc.needs, "goal", lambda n: n.goal, {g.id for g in acc.goals})
     _check_ref(acc.needs, "release", lambda n: n.release, {r.id for r in acc.releases})
     _check_ref(acc.needs, "role", lambda n: n.role, {p.id for p in acc.roles})
+    _check_source_roles(acc.needs, {p.id for p in acc.roles})
     _check_argument(acc.argument)
     return Model(
         needs=tuple(acc.needs),
@@ -424,6 +428,21 @@ def _check_ref(
             raise LoaderError(f"need {need.id!r}: {role} {ref!r} is not a known {role} id")
 
 
+def _check_source_roles(needs: list[Need], known: set[str]) -> None:
+    """Every ``source.role`` that is set must name a declared role id (like ``need.role``, #52).
+
+    Validated unconditionally: ``role`` is a new, opt-in field, so there is no migration reason to
+    be lax — a dangling role on a source is a typo the author owns, surfaced at load, not a silent
+    unknown that only shows as missing provenance later.
+    """
+    for need in needs:
+        for i, s in enumerate(need.sources):
+            if s.role is not None and s.role not in known:
+                raise LoaderError(
+                    f"need {need.id!r}: source[{i}] role {s.role!r} is not a known role id"
+                )
+
+
 def _check_argument(argument: list[ArgNode]) -> None:
     """Every ``supported_by``/``in_context_of`` link must name a known argument node.
 

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/model.py

@@ -74,6 +74,7 @@ class Source:
 
     kind: SourceKind
     who: str | None = None
+    role: str | None = None  # id of the Role the `who` spoke as — whose signal this is (#52 follow-up)
     date: str | None = None
     quote: str | None = None
     locator: str | None = None
@@ -198,6 +199,7 @@ class Need:
     release: str | None = None  # id of the Release slice this need ships in; None = unslotted
     product: bool = True  # False = infra/NFR/internal, excluded from product coverage (#48)
     draft: bool = False  # True = staged, not yet counted on the board until promoted (#60)
+    draft_added: str | None = None  # ISO date this need was staged (#60); lets a lint age-gate it later
     withdrawn: Withdrawal | None = None  # a decision against this need — off the board (#74)
     answer: Answer | None = (
         None  # which way a settled need resolved (yes/no/inconclusive); None=open-ended

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/report_html.py

@@ -361,7 +361,7 @@ function renderDetail(n) {
   let srcHtml;
   if (!n.sources.length) srcHtml = '<span class="warn">no source — this need is an opinion</span>';
   else srcHtml = n.sources.map(s => {
-    const head = `<span class="tag">${esc(s.kind)}</span>${s.who?" "+esc(s.who):""}${s.date?' <span class="meta">· '+esc(s.date)+'</span>':""}`;
+    const head = `<span class="tag">${esc(s.kind)}</span>${s.who?" "+esc(s.who):""}${s.role?' <span class="meta">('+esc(s.role)+')</span>':""}${s.date?' <span class="meta">· '+esc(s.date)+'</span>':""}`;
     const q = s.quote ? `<div class="q">“${esc(s.quote)}”</div>` : "";
     const loc = s.locator ? `<div class="meta">${esc(s.locator)}</div>` : "";
     return `<div class="src">${head}${q}${loc}</div>`;

{prodc-0.3.73 → prodc-0.3.75}/src/prodc/writer.py

@@ -216,6 +216,22 @@ def _render_edit(old_text: str, doc: dict[str, object], need_id: str) -> str:
     return "".join(lines[:start]) + block + "".join(lines[end:])
 
 
+def _render_delete(old_text: str, doc: dict[str, object], need_id: str) -> str:
+    """Re-render after removing a need, excising only its block to keep every other comment (#60).
+
+    The mirror of :func:`_render_edit`: find the need's span and drop it from the original text,
+    so the file header and the surrounding needs stay byte-for-byte. Falls back to a full re-dump
+    of ``doc`` (with the need already removed) when the file's shape is anything the splice isn't
+    sure of; the reload gate in :func:`_validated` guards correctness either way.
+    """
+    lines = old_text.splitlines(keepends=True)
+    span = _need_block_span(lines, need_id)
+    if span is None:
+        return _dump(doc)
+    start, end = span[0], span[1]
+    return "".join(lines[:start]) + "".join(lines[end:])
+
+
 def _read_doc(path: Path) -> tuple[dict[str, object], str]:
     text = path.read_text(encoding="utf-8")
     try:
@@ -372,6 +388,7 @@ def capture_source(
     *,
     kind: str,
     who: str | None,
+    role: str | None = None,
     date: str | None,
     quote: str | None,
     locator: str | None,
@@ -384,6 +401,8 @@ def capture_source(
     Records evidence as given; the loader's soft hygiene checks (a primary source wants a who and a
     quote-or-locator, a secondary source wants a locator) still apply on the next read.
     ``observed_at`` dates when the evidence was recorded, so the board can flag stale needs (#58).
+    ``role`` records which declared role the ``who`` spoke as (validated against ``roles:`` on the
+    next load) — whose signal it is, orthogonal to the evidence tier (#52 follow-up).
     """
     kind = _canonical_kind(kind)
     path, _ = _locate(config, need_id)
@@ -393,6 +412,7 @@ def capture_source(
     source: dict[str, object] = {"kind": kind}
     for key, value in (
         ("who", who),
+        ("role", role),
         ("date", date),
         ("quote", quote),
         ("locator", locator),
@@ -495,6 +515,31 @@ def reinstate(config: Config, need_id: str, *, expect_sha: str | None, dry_run:
     return _validated(config, path, old_text, _render_edit(old_text, doc, need_id), dry_run)
 
 
+def delete_need(
+    config: Config, need_id: str, *, expect_sha: str | None = None, dry_run: bool
+) -> Edit:
+    """Remove a need from its file entirely — the hard-delete write path (#60).
+
+    Unlike :func:`withdraw` (which keeps the need as a dated decision-against record), this erases
+    it. The reload gate makes it referentially safe: a need still pointed at by another's
+    ``children``/``variant_of`` or a ``need:`` proof fails to load after the excision, so the write
+    is reverted and refused rather than leaving a dangling reference. Comment-safe (the #53 splice,
+    reversed): only the deleted need's block leaves the file.
+    """
+    path, _ = _locate(config, need_id)
+    doc, old_text = _read_doc(path)
+    if expect_sha is not None and _sha256(old_text) != expect_sha:
+        raise WriteError(f"{path.name} changed since it was read (optimistic lock)")
+    needs = _need_list(doc, path)
+    kept: list[object] = [
+        raw
+        for raw in needs
+        if not (isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id)
+    ]
+    doc["needs"] = kept
+    return _validated(config, path, old_text, _render_delete(old_text, doc, need_id), dry_run)
+
+
 def accept(
     config: Config,
     need_id: str,
@@ -603,6 +648,7 @@ def add_need(
     }
     if draft:
         new_need["draft"] = True
+        new_need["draft_added"] = today  # stamped so a lint age-gate can fire later (#60)
     needs.append(new_need)
     return _validated(config, target, old_text, _dump(doc), dry_run)
 

{prodc-0.3.73 → prodc-0.3.75}/tests/test_cli.py

@@ -176,6 +176,18 @@ def test_portfolio_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> N
     assert payload["totals"]["boards"] == 1 and payload["totals"]["total"] == 3
 
 
+def test_portfolio_excludes_drafts(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    import json
+
+    # A draft (#60) must not inflate a repo's portfolio line — same board as status/plan.
+    cfg = _project(tmp_path / "alpha")
+    with (tmp_path / "alpha" / "needs" / "a.yaml").open("a", encoding="utf-8") as f:
+        f.write("  - id: DRAFT-1\n    text: a staged idea\n    draft: true\n")
+    main(["portfolio", str(cfg), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["boards"][0]["total"] == 3  # still 3, the draft is off the counted board
+
+
 def test_portfolio_bad_config_exits_2(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
     code = main(["portfolio", str(tmp_path / "nope.toml")])
     capsys.readouterr()

{prodc-0.3.73 → prodc-0.3.75}/tests/test_drafts.py

@@ -127,3 +127,47 @@ def test_promote_via_set_draft_false(tmp_path: Path, capsys: pytest.CaptureFixtu
     main(["status", "--config", str(cfg), "--json"])
     payload = json.loads(capsys.readouterr().out)
     assert {n["id"] for n in payload["needs"]} == {"N-1", "D-1"}
+
+
+_AGE_NEEDS = """
+needs:
+  - id: N-1
+    text: user can see a thing
+  - id: OLD-1
+    text: a long-forgotten draft
+    draft: true
+    draft_added: 2020-01-01
+  - id: UNDATED-1
+    text: a draft with no staged date
+    draft: true
+"""
+
+
+def test_lint_flags_stale_draft(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    toml = _TOML + "\n[lint]\ndraft_max_age_days = 30\n"
+    cfg = _project(tmp_path, toml=toml, needs=_AGE_NEEDS)
+    code = main(["lint", "--config", str(cfg)])
+    out = capsys.readouterr().out
+    assert code == 0  # an old draft is a warning, not a hard error
+    assert "OLD-1: draft staged" in out
+    assert "UNDATED-1: draft with no staged date" in out
+
+
+def test_lint_no_draft_gate_without_knob(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    cfg = _project(tmp_path, needs=_AGE_NEEDS)  # no [lint].draft_max_age_days
+    main(["lint", "--config", str(cfg)])
+    assert "draft staged" not in capsys.readouterr().out
+
+
+def test_config_rejects_bad_draft_max_age_days(tmp_path: Path) -> None:
+    from prodc.config import ConfigError
+
+    toml = _TOML + "\n[lint]\ndraft_max_age_days = 0\n"
+    with pytest.raises(ConfigError, match="draft_max_age_days"):
+        Config.load(_project(tmp_path, toml=toml))

prodc-0.3.75/tests/test_review.py

@@ -0,0 +1,121 @@
+"""`prodc review`: triage staged drafts — list, promote, drop (#60 follow-up)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from prodc.cli import main
+from prodc.config import Config
+from prodc.loader import load
+
+_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+"""
+
+_NEEDS = """\
+# header comment, must survive
+needs:
+  - id: N-1
+    text: the owner can see a delivered thing
+    proofs: ["x:1"]
+  - id: D-1
+    text: the owner can see a delivered thing
+    draft: true
+    draft_added: 2026-10-10
+  - id: D-2
+    text: a totally unrelated vacuum request
+    draft: true
+"""
+
+
+def _project(tmp_path: Path, needs: str = _NEEDS) -> Path:
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text(_TOML, encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
+    return tmp_path / "prodc.toml"
+
+
+def test_review_lists_only_drafts(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    main(["review", "--config", str(_project(tmp_path)), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    ids = {d["id"] for d in payload["drafts"]}
+    assert ids == {"D-1", "D-2"}  # N-1 is on the board, not a draft
+
+
+def test_review_list_carries_staged_date_and_dup(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    main(["review", "--config", str(_project(tmp_path)), "--json"])
+    rows = {d["id"]: d for d in json.loads(capsys.readouterr().out)["drafts"]}
+    assert rows["D-1"]["staged"] == "2026-10-10"
+    # D-1 is near-identical to N-1 → a duplicate hit; D-2 is unrelated → none
+    assert rows["D-1"]["duplicate"] is not None
+    assert rows["D-1"]["duplicate"]["id"] == "N-1"
+    assert rows["D-2"]["duplicate"] is None
+
+
+def test_review_promote_sets_draft_false(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    cfg = _project(tmp_path)
+    code = main(["review", "--promote", "D-1", "--config", str(cfg)])
+    assert code == 0
+    capsys.readouterr()
+    by_id = {n.id: n for n in load(Config.load(cfg)).needs}
+    assert by_id["D-1"].draft is False and by_id["D-2"].draft is True
+
+
+def test_review_drop_deletes_the_need(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    cfg = _project(tmp_path)
+    code = main(["review", "--drop", "D-2", "--config", str(cfg)])
+    assert code == 0
+    capsys.readouterr()
+    ids = {n.id for n in load(Config.load(cfg)).needs}
+    assert ids == {"N-1", "D-1"}  # D-2 is gone from the file
+
+
+def test_review_promote_all_except_dropped(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    cfg = _project(tmp_path)
+    code = main(["review", "--promote-all", "--drop", "D-2", "--config", str(cfg)])
+    assert code == 0
+    capsys.readouterr()
+    by_id = {n.id: n for n in load(Config.load(cfg)).needs}
+    assert "D-2" not in by_id  # dropped
+    assert by_id["D-1"].draft is False  # promoted
+
+
+def test_review_refuses_non_draft(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    cfg = _project(tmp_path)
+    code = main(["review", "--drop", "N-1", "--config", str(cfg)])
+    assert code == 2
+    assert "not a staged draft" in capsys.readouterr().err
+
+
+def test_review_refuses_id_in_both_lists(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    cfg = _project(tmp_path)
+    code = main(["review", "--promote", "D-1", "--drop", "D-1", "--config", str(cfg)])
+    assert code == 2
+    assert "both --promote and --drop" in capsys.readouterr().err
+
+
+def test_review_dry_run_writes_nothing(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    cfg = _project(tmp_path)
+    before = (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
+    code = main(["review", "--promote-all", "--dry-run", "--config", str(cfg)])
+    assert code == 0
+    assert (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8") == before
+    assert "dry-run" in capsys.readouterr().out
+
+
+def test_review_preserves_header_comment(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    cfg = _project(tmp_path)
+    main(["review", "--drop", "D-2", "--config", str(cfg)])
+    capsys.readouterr()
+    text = (tmp_path / "needs" / "a.yaml").read_text(encoding="utf-8")
+    assert "# header comment, must survive" in text

prodc-0.3.75/tests/test_source_role.py

@@ -0,0 +1,126 @@
+"""Source.role (#52 follow-up): which declared role vouched for the evidence, + label deprecation."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from prodc.board import warrant
+from prodc.config import Config
+from prodc.loader import LoaderError, load
+from prodc.model import Need, Source, SourceKind
+from prodc.writer import capture_source
+
+_TOML = "[prodc]\nneeds = [\"needs/*.yaml\"]\n"
+
+_NEEDS = """
+roles:
+  - id: owner
+    text: owns the roastery
+needs:
+  - id: N-1
+    text: the owner can see orders
+    sources:
+      - kind: primary
+        who: Jordan
+        role: owner
+        date: 2026-01-01
+        quote: "I need this"
+"""
+
+
+def _project(tmp_path: Path, needs: str = _NEEDS, toml: str = _TOML) -> Config:
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text(toml, encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
+    return Config.load(tmp_path / "prodc.toml")
+
+
+def test_loader_parses_source_role(tmp_path: Path) -> None:
+    need = load(_project(tmp_path)).needs[0]
+    assert need.sources[0].role == "owner"
+
+
+def test_source_role_orthogonal_to_kind() -> None:
+    # role is provenance, not a strength tier — it does not change ranking
+    s = Source(kind=SourceKind.PRIMARY, who="J", role="owner")
+    n = Need(id="N", text="t", sources=(s,))
+    assert n.strongest_kind is SourceKind.PRIMARY  # role plays no part
+
+
+def test_warrant_shows_role_on_primary(tmp_path: Path) -> None:
+    need = load(_project(tmp_path)).needs[0]
+    assert warrant(need) == "primary:Jordan (owner)"
+
+
+def test_warrant_without_role_is_unchanged() -> None:
+    n = Need(id="N", text="t", sources=(Source(kind=SourceKind.PRIMARY, who="Jo"),))
+    assert warrant(n) == "primary:Jo"
+
+
+def test_dangling_source_role_rejected(tmp_path: Path) -> None:
+    needs = _NEEDS.replace("role: owner", "role: nobody")
+    with pytest.raises(LoaderError, match="source\\[0\\] role 'nobody' is not a known role id"):
+        load(_project(tmp_path, needs=needs))
+
+
+def test_show_json_carries_source_role(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    _project(tmp_path)
+    main(["show", "N-1", "--config", str(tmp_path / "prodc.toml"), "--json"])
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["sources"][0]["role"] == "owner"
+
+
+def test_capture_writes_source_role(tmp_path: Path) -> None:
+    cfg = _project(
+        tmp_path,
+        needs="roles:\n  - id: owner\n    text: owns it\nneeds:\n  - id: N-1\n    text: t\n",
+    )
+    capture_source(
+        cfg,
+        "N-1",
+        kind="primary",
+        who="Jordan",
+        role="owner",
+        date="2026-02-02",
+        quote="I said so",
+        locator=None,
+        expect_sha=None,
+        dry_run=False,
+    )
+    need = load(cfg).needs[0]
+    assert need.sources[-1].role == "owner" and need.sources[-1].who == "Jordan"
+
+
+def test_capture_dangling_role_rejected_by_gate(tmp_path: Path) -> None:
+    cfg = _project(
+        tmp_path,
+        needs="roles:\n  - id: owner\n    text: owns it\nneeds:\n  - id: N-1\n    text: t\n",
+    )
+    with pytest.raises(Exception, match="not a known role id"):
+        capture_source(
+            cfg,
+            "N-1",
+            kind="primary",
+            who="Jordan",
+            role="ghost",
+            date="2026-02-02",
+            quote="q",
+            locator=None,
+            expect_sha=None,
+            dry_run=False,
+        )
+
+
+def test_lint_warns_on_deprecated_label(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    needs = 'who: jordan\nlabel: "design partner"\nneeds:\n  - id: N-1\n    text: t\n'
+    _project(tmp_path, needs=needs)
+    main(["lint", "--config", str(tmp_path / "prodc.toml")])
+    out = capsys.readouterr().out
+    assert "'label'" in out and "deprecated" in out

{prodc-0.3.73 → prodc-0.3.75}/tests/test_writer.py

@@ -9,7 +9,14 @@ import pytest
 
 from prodc.config import Config
 from prodc.loader import load
-from prodc.writer import WriteError, add_need, add_role, capture_source, set_field
+from prodc.writer import (
+    WriteError,
+    add_need,
+    add_role,
+    capture_source,
+    delete_need,
+    set_field,
+)
 
 
 def _proj(tmp_path: Path, body: str) -> Config:
@@ -254,3 +261,61 @@ def test_add_role_dry_run_leaves_no_file(tmp_path: Path) -> None:
     edit = add_role(cfg, "owner", "owns it", file="needs/roles.yaml", dry_run=True)
     assert "owner" in edit.diff
     assert not (cfg.root / "needs" / "roles.yaml").exists()  # dry-run wrote nothing
+
+
+def test_delete_need_removes_the_block_keeping_others(tmp_path: Path) -> None:
+    cfg = _proj(
+        tmp_path,
+        "# keep me\nneeds:\n  - id: N-1\n    text: one\n  - id: N-2\n    text: two\n",
+    )
+    delete_need(cfg, "N-1", dry_run=False)
+    text = _a_yaml(cfg)
+    assert {n.id for n in load(cfg).needs} == {"N-2"}
+    assert "# keep me" in text  # header comment survives the splice
+
+
+def test_delete_need_unknown_id_rejected(tmp_path: Path) -> None:
+    cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: t\n")
+    with pytest.raises(WriteError, match="no need 'N-9'"):
+        delete_need(cfg, "N-9", dry_run=False)
+
+
+def test_delete_need_dangling_reference_reverts(tmp_path: Path) -> None:
+    # N-2 is a child of flow N-1; deleting N-2 would dangle the reference, so the reload gate
+    # must reject the write and restore the file.
+    body = (
+        "needs:\n"
+        "  - id: N-1\n    text: a flow\n    children: [N-2]\n"
+        "  - id: N-2\n    text: a step\n    proofs: ['x:1']\n"
+    )
+    cfg = _proj(tmp_path, body)
+    before = _a_yaml(cfg)
+    with pytest.raises(WriteError, match="edit rejected"):
+        delete_need(cfg, "N-2", dry_run=False)
+    assert _a_yaml(cfg) == before  # reverted
+
+
+def test_delete_need_dry_run_leaves_file(tmp_path: Path) -> None:
+    cfg = _proj(tmp_path, "needs:\n  - id: N-1\n    text: one\n  - id: N-2\n    text: two\n")
+    before = _a_yaml(cfg)
+    edit = delete_need(cfg, "N-1", dry_run=True)
+    assert _a_yaml(cfg) == before  # nothing written
+    assert "N-1" in edit.diff and edit.diff.startswith("---")
+
+
+def test_add_draft_stamps_draft_added(tmp_path: Path) -> None:
+    cfg = _proj(tmp_path, "needs: []\n")
+    add_need(
+        cfg,
+        "D-1",
+        "a staged idea",
+        who="agent",
+        kind="assumption",
+        file="needs/a.yaml",
+        draft=True,
+        expect_sha=None,
+        dry_run=False,
+    )
+    need = {n.id: n for n in load(cfg).needs}["D-1"]
+    assert need.draft is True
+    assert need.draft_added == datetime.date.today().isoformat()