prodc 0.3.72__tar.gz → 0.3.75__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.3.72"
+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.72 → 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` |
@@ -80,8 +83,9 @@ Read first, then act, then check.
 | act on a need going green (notify a tracker, etc.) | `prodc sync` — runs the `[callbacks]` commands for needs whose state changed since the last sync (`--dry-run` to preview) |
 | gate in CI | `prodc lint --strict` |
 
-Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <toml>…`
-(roll up many repos into one scoreboard), and `prodc diff <snapshot.json>` (what changed since a
+Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <path>…`
+(roll up many boards into one scoreboard + totals; a path is a prodc.toml or a dir to discover
+boards under), and `prodc diff <snapshot.json>` (what changed since a
 saved `status --json`). `prodc status` also takes `--goal <id>`, `--columns id,state,text,warrant`,
 `--wide`, `--include-drafts`, and `--stale <days>`.
 

{prodc-0.3.72 → 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.72 → 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,8 +331,48 @@ def main(argv: list[str] | None = None) -> int:
     )
     ri.set_defaults(func=cmd_reinstate)
 
-    pf = sub.add_parser("portfolio", help="roll up many repos into one scoreboard")
-    pf.add_argument("configs", nargs="+", metavar="PRODC_TOML", help="one or more prodc.toml paths")
+    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",
+        nargs="+",
+        metavar="PATH",
+        help="prodc.toml paths and/or directories to discover boards under",
+    )
+    pf.add_argument(
+        "--max-depth",
+        type=int,
+        default=4,
+        help="how deep to descend when discovering boards under a directory (default 4)",
+    )
     pf.add_argument("--json", action="store_true", help="machine-readable output")
     pf.set_defaults(func=cmd_portfolio)
 

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

@@ -50,13 +50,22 @@ from ..writer import (
     add_role,
     attest,
     capture_source,
+    delete_need,
     link_variant_group,
     reinstate,
     set_field,
     set_importance,
     withdraw,
 )
-from .common import RepoRow, emit_edit, exit_code, git_rev, load_or_report
+from .common import (
+    RepoRow,
+    discover_configs,
+    emit_edit,
+    exit_code,
+    git_rev,
+    load_or_report,
+    portfolio_totals,
+)
 from .render import (
     COLUMNS,
     provenance_counts,
@@ -128,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] = []
@@ -176,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
@@ -523,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)
@@ -536,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,
@@ -565,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)
@@ -582,12 +763,33 @@ def _repo_row(config_path: str) -> RepoRow:
 
 
 def cmd_portfolio(args: argparse.Namespace) -> int:
-    """Roll up many repos into one scoreboard — coverage, must-HOLEs, provenance per repo."""
-    rows = [_repo_row(path) for path in args.configs]
+    """Roll up many boards into one scoreboard — coverage, must-HOLEs, provenance per board.
+
+    Each argument is a ``prodc.toml`` path or a directory to discover boards under (every
+    ``prodc.toml`` beneath it, pruning VCS/vendor/build and hidden dirs, capped at ``--max-depth``).
+    Boards stay separate rows; a totals footer aggregates the clean ones. Never a merged board.
+    """
+    paths: list[str] = []
+    for arg in args.configs:
+        p = Path(arg)
+        if p.is_dir():
+            paths.extend(str(c) for c in discover_configs(p, max_depth=args.max_depth))
+        else:
+            paths.append(arg)
+    seen: set[str] = set()
+    unique: list[str] = []
+    for path in paths:
+        key = str(Path(path).resolve())
+        if key not in seen:
+            seen.add(key)
+            unique.append(path)
+    rows = [_repo_row(path) for path in unique]
+    totals = portfolio_totals(rows)
     if args.json:
-        print(json.dumps([asdict(r) for r in rows], indent=2))
+        payload = {"boards": [asdict(r) for r in rows], "totals": asdict(totals)}
+        print(json.dumps(payload, indent=2))
     else:
-        print(render_portfolio(rows))
+        print(render_portfolio(rows, totals))
     return 2 if any(r.error is not None for r in rows) else 0
 
 

{prodc-0.3.72 → prodc-0.3.75}/src/prodc/cli/common.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from dataclasses import dataclass
 from pathlib import Path
@@ -100,3 +101,79 @@ class RepoRow:
     coverage: float
     provenance: dict[str, int]
     error: str | None = None
+
+
+@dataclass(frozen=True)
+class PortfolioTotals:
+    """The aggregate across every board in a portfolio — a footer, not a merged board.
+
+    Error rows are excluded (a board that would not load contributes no counts). ``coverage`` is
+    the pooled ``delivered / total``, which is not the mean of the per-board percentages.
+    """
+
+    boards: int  # how many boards loaded cleanly and are summed here
+    delivered: int
+    total: int
+    must_hole: int
+    broken: int
+    coverage: float
+
+
+def portfolio_totals(rows: list[RepoRow]) -> PortfolioTotals:
+    """Sum the clean rows into a :class:`PortfolioTotals` footer."""
+    ok = [r for r in rows if r.error is None]
+    delivered = sum(r.delivered for r in ok)
+    total = sum(r.total for r in ok)
+    return PortfolioTotals(
+        boards=len(ok),
+        delivered=delivered,
+        total=total,
+        must_hole=sum(r.must_hole for r in ok),
+        broken=sum(r.broken for r in ok),
+        coverage=round(delivered / total, 4) if total else 0.0,
+    )
+
+
+# Directory names never descended into during board discovery: VCS, virtualenvs, dependency and
+# build trees. Any name starting with "." is pruned too (handled in the walk), so a vendored or
+# example prodc.toml buried in one of these is never mistaken for a board.
+_PRUNE_DIRS = frozenset(
+    {
+        ".git",
+        "node_modules",
+        ".venv",
+        "venv",
+        "__pycache__",
+        "dist",
+        "build",
+        "target",
+        ".tox",
+        ".mypy_cache",
+        ".ruff_cache",
+        "site-packages",
+        "vendor",
+    }
+)
+
+
+def discover_configs(root: Path, *, max_depth: int = 4) -> list[Path]:
+    """Every ``prodc.toml`` under ``root``, for the portfolio roll-up — bounded so it can't run away.
+
+    A plain recursive scan is a footgun: it descends into ``.git``/``node_modules``/build trees and
+    picks up vendored or example configs. So this prunes those (and every ``.``-prefixed dir) and
+    caps the descent at ``max_depth`` directories below ``root``. Returns sorted, de-duplicated
+    paths; a board is the directory that holds the ``prodc.toml``.
+    """
+    root = root.resolve()
+    found: set[Path] = set()
+    for dirpath, dirnames, filenames in os.walk(root):
+        if "prodc.toml" in filenames:
+            found.add(Path(dirpath) / "prodc.toml")
+        depth = len(Path(dirpath).relative_to(root).parts)
+        # Prune in place so os.walk never descends into the skipped dirs, then stop at the depth cap.
+        dirnames[:] = (
+            []
+            if depth >= max_depth
+            else [d for d in dirnames if d not in _PRUNE_DIRS and not d.startswith(".")]
+        )
+    return sorted(found)

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

@@ -22,7 +22,7 @@ from ..model import (
     ears_shape,
 )
 from ..status import Handoff, Recurrence, Summary, rank, state_priority
-from .common import RepoRow, brief_open
+from .common import PortfolioTotals, RepoRow, brief_open
 
 _LABEL = {
     NeedState.DELIVERED: "DELIVERED",
@@ -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)
@@ -380,7 +385,9 @@ def render_argument(model: Model, defects: list[str]) -> str:
     return "\n".join(out)
 
 
-def render_portfolio(rows: list[RepoRow]) -> str:
+def render_portfolio(rows: list[RepoRow], totals: PortfolioTotals | None = None) -> str:
+    if not rows:
+        return "  no boards found"
     out = [f"  {'repo':<18} {'cov':>4}  {'must-HOLE':>9}  {'BROKEN':>6}   prov prim/sec/asm/op"]
     for row in rows:
         if row.error is not None:
@@ -390,4 +397,12 @@ def render_portfolio(rows: list[RepoRow]) -> str:
         prov = f"{p['primary']}/{p['secondary']}/{p['assumption']}/{p['opinion']}"
         cov = f"{round(row.coverage * 100)}%"
         out.append(f"  {row.repo:<18} {cov:>4}  {row.must_hole:>9}  {row.broken:>6}   {prov}")
+    if totals is not None:
+        cov = f"{round(totals.coverage * 100)}%"
+        label = f"TOTAL ({totals.boards} boards)"
+        out.append(f"  {'─' * 48}")
+        out.append(
+            f"  {label:<18} {cov:>4}  {totals.must_hole:>9}  {totals.broken:>6}   "
+            f"{totals.delivered}/{totals.total} delivered"
+        )
     return "\n".join(out)

{prodc-0.3.72 → 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.72 → 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.72 → 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.