prodc 0.3.73__tar.gz → 0.3.76__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.3.73"
+version = "0.3.76"
 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.76}/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,10 +70,12 @@ 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]` |
+| relink a BROKEN proof (renamed test) | `prodc suggest --relink [<id>] [--apply] [--dry-run]` — proposes the nearest live inventory entry to replace the broken locator |
 | link a recurring want to a shared baseline | `prodc recurrence --suggest --apply --baseline-id <id> --file needs/<f>.yaml` |
 | record a human/AI review of the warrant | `prodc attest <id> --by <who> --date <ISO> [--ai]` |
 | record a human acceptance pass | `prodc accept <id> --who <person> --date <ISO>` |

{prodc-0.3.73 → prodc-0.3.76}/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.76}/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",
@@ -397,10 +433,15 @@ def main(argv: list[str] | None = None) -> int:
     sg.add_argument(
         "--kind", default=None, metavar="ADAPTER", help="only suggest from this adapter name"
     )
+    sg.add_argument(
+        "--relink",
+        action="store_true",
+        help="BROKEN-need mode: propose a live inventory entry to replace each broken locator (#54)",
+    )
     sg.add_argument(
         "--apply",
         action="store_true",
-        help="write the best suggestion per need as a proof (#54); honours --min-score",
+        help="write the best suggestion per need as a proof (relink: replace the broken one) (#54)",
     )
     sg.add_argument(
         "--dry-run",

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

@@ -33,11 +33,13 @@ from ..report import render_markdown
 from ..report_html import render_html
 from ..status import (
     ProofSuggestion,
+    RelinkSuggestion,
     applicable_needs,
     argument_defects,
     evidence_age_days,
     proof_suggestions,
     recurrence,
+    relink_suggestions,
     resolve,
     summarize,
 )
@@ -50,8 +52,10 @@ from ..writer import (
     add_role,
     attest,
     capture_source,
+    delete_need,
     link_variant_group,
     reinstate,
+    relink_proof,
     set_field,
     set_importance,
     withdraw,
@@ -136,6 +140,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 +229,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 +578,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 +717,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 +747,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)
@@ -781,7 +957,7 @@ def cmd_agent(args: argparse.Namespace) -> int:
 
 
 def cmd_suggest(args: argparse.Namespace) -> int:
-    """Propose candidate proof locators for HOLE needs from the adapters' inventories (#54)."""
+    """Propose candidate proof locators for HOLE needs (or relink BROKEN ones) from the inventories (#54)."""
     loaded = load_or_report(args)
     if loaded is None:
         return 2
@@ -793,6 +969,8 @@ def cmd_suggest(args: argparse.Namespace) -> int:
         if not results:
             print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
             return 2
+    if args.relink:
+        return _cmd_relink(cfg, results, args)
     suggestions = proof_suggestions(
         results, cfg.adapters, min_score=args.min_score, top=args.top, kind=args.kind
     )
@@ -871,6 +1049,88 @@ def _apply_suggestions(
     return 0
 
 
+def _cmd_relink(cfg: Config, results: list[NeedResult], args: argparse.Namespace) -> int:
+    """Propose (or --apply) a live inventory entry to replace each BROKEN proof locator (#54)."""
+    suggestions = relink_suggestions(
+        results, cfg.adapters, min_score=args.min_score, top=args.top, kind=args.kind
+    )
+    if args.apply:
+        return _apply_relinks(cfg, suggestions, args)
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "need": s.need.id,
+                        "adapter": s.adapter,
+                        "broken": s.broken,
+                        "locator": s.locator,
+                        "score": round(s.score, 4),
+                    }
+                    for s in suggestions
+                ],
+                indent=2,
+            )
+        )
+    else:
+        last = None
+        for s in suggestions:
+            if s.need.id != last:
+                print(f"{s.need.id}: {s.need.text}")
+                last = s.need.id
+            print(f"    {s.score:.2f}  {s.broken} → {s.locator}")
+        print(f"suggest --relink: {len(suggestions)} candidate(s) at min-score {args.min_score:.2f}")
+    return 0
+
+
+def _apply_relinks(
+    cfg: Config, suggestions: list[RelinkSuggestion], args: argparse.Namespace
+) -> int:
+    """Apply the best relink per broken locator, printing each need's diff (#54 relink).
+
+    Keyed by ``(need, broken locator)`` so a need with two broken proofs relinks both to their own
+    best candidate. Each is one reload-gated single-file edit (:func:`relink_proof`), applied in a
+    stable order; a rejected write aborts with a non-zero exit (earlier writes stand).
+    """
+    best: dict[tuple[str, str], RelinkSuggestion] = {}
+    for s in suggestions:
+        best.setdefault((s.need.id, s.broken), s)
+    applied: list[tuple[RelinkSuggestion, Edit]] = []
+    for key in sorted(best):
+        s = best[key]
+        try:
+            edit = relink_proof(cfg, s.need.id, s.broken, s.locator, dry_run=args.dry_run)
+        except WriteError as exc:
+            print(f"prodc: {exc}", file=sys.stderr)
+            return 2
+        applied.append((s, edit))
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "need": s.need.id,
+                        "broken": s.broken,
+                        "locator": s.locator,
+                        "score": round(s.score, 4),
+                        "file": edit.path.name,
+                        "dry_run": args.dry_run,
+                        "diff": edit.diff,
+                    }
+                    for s, edit in applied
+                ],
+                indent=2,
+            )
+        )
+    else:
+        verb = "would relink" if args.dry_run else "relinked"
+        for s, edit in applied:
+            print(f"{verb} {s.broken} → {s.locator} on {s.need.id} ({s.score:.2f}) in {edit.path.name}")
+            print(edit.diff, end="")
+        print(f"suggest --relink --apply: {verb} {len(applied)} locator(s)")
+    return 0
+
+
 def cmd_recurrence(args: argparse.Namespace) -> int:
     """Show baselines shared across clients; `--suggest` proposes unlinked variant groups (#56)."""
     loaded = load_or_report(args)

{prodc-0.3.73 → prodc-0.3.76}/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.76}/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.76}/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.76}/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.76}/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.76}/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>`;