prodc 0.3.78__tar.gz → 0.3.79__tar.gz

{prodc-0.3.78 → prodc-0.3.79}/PKG-INFO

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

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

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/agent.md

@@ -72,6 +72,8 @@ Read first, then act, then check.
 | 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` |
+| declare a product principle (the vision, held as given) | `prodc add principle <id> --text "…" --file needs/<f>.yaml` — the frame that decides between clients who want opposite things; what an `out_of_scope` decision cites |
+| revise a principle (fires the re-review ripple) | `prodc revise principle <id> [--text "…"] [--date ISO]` — re-stamps `revised_at`, so every need withdrawn under it with an earlier date comes back up |
 | 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]` |

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/board.py

@@ -28,6 +28,7 @@ from .model import (
 )
 from .status import (
     Handoff,
+    PrincipleReport,
     Recurrence,
     Summary,
     evidence_age_days,
@@ -36,6 +37,7 @@ from .status import (
     handoffs,
     last_observed,
     orphans,
+    principle_report,
     recurrence,
     release_report,
     resolve,
@@ -106,6 +108,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
                     "reason": need.withdrawn.reason,
                     "date": need.withdrawn.date,
                     "kind": need.withdrawn.kind.value,
+                    "principle": need.withdrawn.principle,
                 }
                 if need.withdrawn
                 else None
@@ -158,6 +161,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
                 "reason": need.withdrawn.reason,
                 "date": need.withdrawn.date,
                 "kind": need.withdrawn.kind.value,
+                "principle": need.withdrawn.principle,
             }
             if need.withdrawn
             else None
@@ -202,6 +206,7 @@ class ResolvedBoard:
     handoffs: list[Handoff]
     recurrence: list[Recurrence]
     orphans: dict[str, list[str]]
+    principles: list[PrincipleReport]  # over the whole model — declined needs are off the board
 
 
 def gather(
@@ -218,7 +223,8 @@ def gather(
     appends the cross-need board warnings (#44/#45) to the results, as ``prodc status`` does —
     the markdown/HTML reports leave it off, exactly as they did before this was factored out.
     The declared goals/releases/roles come from ``model``; the recurrence/handoffs/orphans views
-    are computed over the resolved ``needs``.
+    are computed over the resolved ``needs``. The principle report reads the whole ``model.needs``:
+    the needs declined under a principle are withdrawn, so the filtered ``needs`` never holds them.
     """
     use_needs = list(model.needs) if needs is None else needs
     results = resolve(use_needs, cfg.adapters, cfg.source_adapters)
@@ -239,4 +245,5 @@ def gather(
         handoffs=handoffs(use_needs),
         recurrence=recurrence(use_needs),
         orphans=orphans(use_needs, cfg.adapters),
+        principles=principle_report(list(model.needs), list(model.principles)),
     )

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/cli/app.py

@@ -29,6 +29,7 @@ from .commands import (
     cmd_reinstate,
     cmd_report,
     cmd_review,
+    cmd_revise,
     cmd_set,
     cmd_show,
     cmd_status,
@@ -165,11 +166,15 @@ def main(argv: list[str] | None = None) -> int:
     st2.set_defaults(func=cmd_set)
 
     ad = sub.add_parser(
-        "add", help="create a new agent-authored need, or declare a role (writes YAML)"
+        "add",
+        help="create a new agent-authored need, or declare a role or a principle (writes YAML)",
     )
-    ad.add_argument("noun", choices=["need", "role"], help="what to add (need or role)")
-    ad.add_argument("need_id", help="the new need's id (or role id for `add role`), e.g. N-9")
-    ad.add_argument("--text", required=True, help="the need text (or the role description)")
+    ad.add_argument("noun", choices=["need", "role", "principle"], help="what to add")
+    ad.add_argument(
+        "need_id",
+        help="the new need's id (or role id for `add role`, principle id for `add principle`), e.g. N-9",
+    )
+    ad.add_argument("--text", required=True, help="the need text (or the role / principle text)")
     ad.add_argument(
         "--who",
         default=None,
@@ -315,6 +320,13 @@ def main(argv: list[str] | None = None) -> int:
         "or duplicate (#74)",
     )
     wd.add_argument("--date", default=None, help="when (ISO, e.g. 2026-10-10; default: today)")
+    wd.add_argument(
+        "--principle",
+        default=None,
+        metavar="ID",
+        help="the product principle this decision rests on (validated against principles:) — revising it "
+        "later flags this decision for re-review",
+    )
     wd.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
     wd.add_argument("--json", action="store_true", help="machine-readable output")
     wd.add_argument(
@@ -345,6 +357,32 @@ def main(argv: list[str] | None = None) -> int:
     )
     ri.set_defaults(func=cmd_reinstate)
 
+    rvz = sub.add_parser(
+        "revise", help="revise a product principle in place — new text and/or a fresh revised_at"
+    )
+    rvz.add_argument("noun", choices=["principle"], help="what to revise (principle)")
+    rvz.add_argument("principle_id", help="the principle id to revise, e.g. P-1")
+    rvz.add_argument(
+        "--text", default=None, help="new principle text (optional; omit to only re-date it)"
+    )
+    rvz.add_argument(
+        "--date",
+        default=None,
+        help="the new revised_at (ISO, e.g. 2026-10-15; default: today) — fires the ripple",
+    )
+    rvz.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    rvz.add_argument("--json", action="store_true", help="machine-readable output")
+    rvz.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diff, don't write"
+    )
+    rvz.add_argument(
+        "--expect-sha",
+        default=None,
+        metavar="SHA256",
+        help="refuse if the file's content hash differs (optimistic lock)",
+    )
+    rvz.set_defaults(func=cmd_revise)
+
     rv = sub.add_parser(
         "review", help="triage staged drafts: list them, or --promote / --drop a batch (#60)"
     )

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/cli/commands.py

@@ -38,6 +38,7 @@ from ..status import (
     argument_defects,
     evidence_age_days,
     importance_revisit_due,
+    principle_report,
     proof_suggestions,
     recurrence,
     relink_suggestions,
@@ -49,6 +50,7 @@ from ..writer import (
     WriteError,
     accept,
     add_need,
+    add_principle,
     add_proof,
     add_role,
     attest,
@@ -57,6 +59,7 @@ from ..writer import (
     link_variant_group,
     reinstate,
     relink_proof,
+    revise_principle,
     set_field,
     set_importance,
     withdraw,
@@ -83,6 +86,7 @@ from .render import (
     render_out_of_scope,
     render_plan,
     render_portfolio,
+    render_principles,
     render_recurrence,
     render_releases,
     render_roles,
@@ -232,6 +236,16 @@ def cmd_lint(args: argparse.Namespace) -> int:
     _annotate_importance_warnings(results, cfg)
     _annotate_draft_age_warnings(results, cfg)
     _annotate_label_deprecation(results)
+    # The principle ripple: a need withdrawn citing a principle that was revised *after* the decision
+    # comes back up — the frame it was judged against has changed since. A warning, never a hard
+    # error; prodc flags, the PM re-decides.
+    for rep in principle_report(needs, list(model.principles)):
+        for n in rep.stale:
+            if n.id in by_id and n.withdrawn is not None:
+                by_id[n.id].warnings.append(
+                    f"withdrawn per principle {rep.principle.id} on {n.withdrawn.date}, but "
+                    f"{rep.principle.id} was revised {rep.principle.revised_at} — re-review the decision"
+                )
     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
@@ -318,6 +332,7 @@ def cmd_status(args: argparse.Namespace) -> int:
                 role_cov,
                 unroled,
                 hos,
+                principles=board.principles,
             )
         )
     else:
@@ -350,6 +365,8 @@ def cmd_status(args: argparse.Namespace) -> int:
             print(render_handoffs(hos))
         if recs:
             print(render_recurrence(recs))
+        if model.principles:
+            print(render_principles(board.principles))
         if orphan_map:
             print(render_orphans(orphan_map))
 
@@ -479,6 +496,22 @@ def cmd_add(args: argparse.Namespace) -> int:
             print(f"prodc: {exc}", file=sys.stderr)
             return 2
         return emit_edit(edit, args.dry_run, args.json)
+    if args.noun == "principle":
+        try:
+            cfg = Config.load(cfg_path)
+            edit = add_principle(
+                cfg,
+                args.need_id,
+                args.text,
+                file=args.file,
+                revised_at=date.today().isoformat(),
+                expect_sha=args.expect_sha,
+                dry_run=args.dry_run,
+            )
+        except (ConfigError, LoaderError, WriteError) as exc:
+            print(f"prodc: {exc}", file=sys.stderr)
+            return 2
+        return emit_edit(edit, args.dry_run, args.json)
     if args.who is None:
         print("prodc: add need requires --who (the author recorded on the source)", file=sys.stderr)
         return 2
@@ -578,6 +611,7 @@ def cmd_withdraw(args: argparse.Namespace) -> int:
             reason=args.reason,
             date=args.date or date.today().isoformat(),
             kind=args.kind,
+            principle=args.principle,
             expect_sha=args.expect_sha,
             dry_run=args.dry_run,
         )
@@ -607,6 +641,33 @@ def cmd_reinstate(args: argparse.Namespace) -> int:
     return emit_edit(edit, args.dry_run, args.json)
 
 
+def cmd_revise(args: argparse.Namespace) -> int:
+    """Revise a product principle in place: optional new text, always a fresh revised_at (the ripple).
+
+    Re-stamping ``revised_at`` is the point — every need withdrawn citing this principle with an
+    earlier date comes back up for re-review (surfaced by `lint`). Comment-safe: only the principle's
+    own block is spliced, the rest of the file is untouched.
+    """
+    cfg_path = Path(args.config)
+    if not cfg_path.exists():
+        print(f"prodc: no config at {cfg_path}", file=sys.stderr)
+        return 2
+    try:
+        cfg = Config.load(cfg_path)
+        edit = revise_principle(
+            cfg,
+            args.principle_id,
+            text=args.text,
+            revised_at=args.date or date.today().isoformat(),
+            expect_sha=args.expect_sha,
+            dry_run=args.dry_run,
+        )
+    except (ConfigError, LoaderError, WriteError) as exc:
+        print(f"prodc: {exc}", file=sys.stderr)
+        return 2
+    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).
 

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/cli/render.py

@@ -21,7 +21,7 @@ from ..model import (
     Role,
     ears_shape,
 )
-from ..status import Handoff, Recurrence, Summary, rank, state_priority
+from ..status import Handoff, PrincipleReport, Recurrence, Summary, rank, state_priority
 from .common import PortfolioTotals, RepoRow, brief_open
 
 _LABEL = {
@@ -261,6 +261,25 @@ def render_recurrence(recs: list[Recurrence]) -> str:
     return "\n".join(out)
 
 
+def render_principles(reports: list[PrincipleReport]) -> str:
+    """The product vision as principles, with the decisions resting on each and which have gone stale.
+
+    An principle is held as given, not validated; ``declined`` are the needs withdrawn citing it, and
+    ``stale`` (the ripple) are those decided before its latest ``revised_at`` — flagged to re-review.
+    """
+    out = ["\nprinciples (the product vision — held as given):"]
+    for rep in reports:
+        a = rep.principle
+        rev = f"revised {a.revised_at}" if a.revised_at else "undated"
+        out.append(f"  {a.id:<6} {rev}  {a.text}")
+        if rep.declined:
+            out.append(f"        declined: {', '.join(n.id for n in rep.declined)}")
+        if rep.stale:
+            ids = ", ".join(n.id for n in rep.stale)
+            out.append(f"        ⚠ decided before the latest revision: {ids} — re-review")
+    return "\n".join(out)
+
+
 def render_show(r: NeedResult, importance_label: str | None = None) -> str:
     """One need as a citable answer — the artifact you drop into a thread."""
     need = r.need
@@ -278,7 +297,8 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
     if need.withdrawn:
         w = need.withdrawn
         tag = "" if w.kind.value == "wont_do" else f" [{w.kind.value}]"
-        lines.append(f"  withdrawn{tag}: {w.reason} ({w.date})")
+        per = f" per {w.principle}" if w.principle else ""
+        lines.append(f"  withdrawn{tag}{per}: {w.reason} ({w.date})")
     if need.description:
         lines.append(f"  description: {need.description}")
     if need.importance is not None:

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/cli/serialize.py

@@ -13,7 +13,7 @@ from ..board import need_payload
 from ..board import warrant as _warrant
 from ..dedup import DupPair, VariantGroup
 from ..model import Goal, Model, NeedResult, NeedState, Release, Role
-from ..status import Handoff, Recurrence, Summary, rank
+from ..status import Handoff, PrincipleReport, Recurrence, Summary, rank
 from .common import brief_open
 
 
@@ -43,6 +43,7 @@ def to_json(
     role_cov: list[tuple[Role, Summary]],
     unroled: list[NeedResult],
     hos: list[Handoff],
+    principles: list[PrincipleReport] | None = None,
 ) -> str:
     payload = {
         "summary": _summary_payload(summary, orphan_map),
@@ -100,6 +101,16 @@ def to_json(
             for goal, gsum in goal_cov
         ],
         "ungoaled": [r.need.id for r in ungoaled],
+        "principles": [
+            {
+                "id": rep.principle.id,
+                "text": rep.principle.text,
+                "revised_at": rep.principle.revised_at,
+                "declined": [n.id for n in rep.declined],
+                "stale": [n.id for n in rep.stale],
+            }
+            for rep in (principles or [])
+        ],
         "needs": [need_payload(r) for r in results],
     }
     return json.dumps(payload, indent=2)

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/loader.py

@@ -25,6 +25,7 @@ from .model import (
     Goal,
     Model,
     Need,
+    Principle,
     Release,
     Role,
     Source,
@@ -131,12 +132,13 @@ def _answer(raw: object, where: str) -> Answer | None:
 
 
 def _withdrawal(raw: object, where: str) -> Withdrawal | None:
-    """Parse ``withdrawn: {reason, date, kind?}`` into a :class:`Withdrawal` (#74).
+    """Parse ``withdrawn: {reason, date, kind?, principle?}`` into a :class:`Withdrawal` (#74).
 
     ``reason`` and ``date`` are required when the key is present — a decision against a need must
     say why and when, the same way an attestation needs who and when. ``kind`` is optional and
     defaults to ``wont_do``; it is validated with the same ``Enum(name) except ValueError`` pattern
-    as ``SourceKind``, so an unknown kind is a :class:`LoaderError` the author owns.
+    as ``SourceKind``, so an unknown kind is a :class:`LoaderError` the author owns. ``principle`` is
+    an optional Principle id, checked against the declared principles once every file is loaded.
     """
     if raw is None:
         return None
@@ -153,7 +155,8 @@ def _withdrawal(raw: object, where: str) -> Withdrawal | None:
         raise LoaderError(
             f"{where}.kind: unknown withdrawal kind {kind_name!r} ({kinds})"
         ) from None
-    return Withdrawal(reason=reason, date=date, kind=kind)
+    principle = _opt_str(tbl.get("principle"), f"{where}.principle")
+    return Withdrawal(reason=reason, date=date, kind=kind, principle=principle)
 
 
 # Old source-kind names (pre-0.3.58) mapped to the primary/secondary/assumption ladder, so
@@ -304,6 +307,20 @@ def _role(raw: object, where: str) -> Role:
     )
 
 
+def _principle(raw: object, where: str) -> Principle:
+    """Parse one ``principles:`` entry — a product commitment with its provenance."""
+    tbl = _as_mapping(raw, where)
+    return Principle(
+        id=_as_str(tbl.get("id"), f"{where}.id"),
+        text=_as_str(tbl.get("text"), f"{where}.text"),
+        revised_at=_opt_str(tbl.get("revised_at"), f"{where}.revised_at"),
+        sources=tuple(
+            _source(s, f"{where}.sources[{i}]")
+            for i, s in enumerate(_as_list(tbl.get("sources"), f"{where}.sources"))
+        ),
+    )
+
+
 def _arg_node(raw: object, where: str) -> ArgNode:
     tbl = _as_mapping(raw, where)
     kind_name = _as_str(tbl.get("kind"), f"{where}.kind")
@@ -336,11 +353,12 @@ class _Loaded:
     goals: list[Goal] = field(default_factory=list[Goal])
     releases: list[Release] = field(default_factory=list[Release])
     roles: list[Role] = field(default_factory=list[Role])
+    principles: list[Principle] = field(default_factory=list[Principle])
     argument: list[ArgNode] = field(default_factory=list[ArgNode])
 
 
 def _load_file(path: Path, seen: dict[str, dict[str, Path]]) -> _Loaded:
-    """Parse one prodc file for every noun list it carries (``needs:``/``goals:``/``releases:``)."""
+    """Parse one prodc file for every noun list it carries (``needs:``/``goals:``/``principles:``/…)."""
     where = path.name
     try:
         doc = yaml.safe_load(path.read_text(encoding="utf-8"))
@@ -376,6 +394,10 @@ def _load_file(path: Path, seen: dict[str, dict[str, Path]]) -> _Loaded:
         role = _role(raw, f"{where}.roles[{i}]")
         _unique("role", role.id)
         out.roles.append(role)
+    for i, raw in enumerate(_as_list(tbl.get("principles"), f"{where}.principles")):
+        principle = _principle(raw, f"{where}.principles[{i}]")
+        _unique("principle", principle.id)
+        out.principles.append(principle)
     for i, raw in enumerate(_as_list(tbl.get("argument"), f"{where}.argument")):
         node = _arg_node(raw, f"{where}.argument[{i}]")
         _unique("argument node", node.id)
@@ -387,10 +409,11 @@ def load(config: Config) -> Model:
     """Read every prodc file once into a :class:`~prodc.model.Model`, then validate cross-refs.
 
     One loader for every noun: ids are unique within their kind, and each string reference
-    (``variant_of``, ``children``, ``goal``, ``release``, ``role``) is checked here as a hard
-    error — a dangling reference to something declared in these files is a typo you own, not a
-    runtime unknown. ``role`` is checked unconditionally like ``goal``/``release``: it is a new
-    field, so (unlike free-text ``who``) there is no migration reason to make it lax.
+    (``variant_of``, ``children``, ``goal``, ``release``, ``role``, a withdrawal's ``principle``) is
+    checked here as a hard error — a dangling reference to something declared in these files is a
+    typo you own, not a runtime unknown. ``role`` is checked unconditionally like
+    ``goal``/``release``: it is a new field, so (unlike free-text ``who``) there is no migration
+    reason to make it lax.
     """
     acc = _Loaded()
     seen: dict[str, dict[str, Path]] = {
@@ -398,6 +421,7 @@ def load(config: Config) -> Model:
         "goal": {},
         "release": {},
         "role": {},
+        "principle": {},
         "argument node": {},
     }
     for pattern in config.need_globs:
@@ -407,19 +431,27 @@ def load(config: Config) -> Model:
             acc.goals.extend(f.goals)
             acc.releases.extend(f.releases)
             acc.roles.extend(f.roles)
+            acc.principles.extend(f.principles)
             acc.argument.extend(f.argument)
     _check_variants(acc.needs)
     _check_children(acc.needs)
     _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_ref(
+        acc.needs,
+        "principle",
+        lambda n: n.withdrawn.principle if n.withdrawn else None,
+        {a.id for a in acc.principles},
+    )
+    _check_source_roles(acc.needs, acc.principles, {p.id for p in acc.roles})
     _check_argument(acc.argument)
     return Model(
         needs=tuple(acc.needs),
         goals=tuple(acc.goals),
         releases=tuple(acc.releases),
         roles=tuple(acc.roles),
+        principles=tuple(acc.principles),
         argument=tuple(acc.argument),
     )
 
@@ -439,18 +471,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:
+def _check_source_roles(needs: list[Need], principles: list[Principle], 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.
+    Validated unconditionally, on a need's sources and a principle's alike: ``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):
+    owners = [("need", n.id, n.sources) for n in needs] + [
+        ("principle", a.id, a.sources) for a in principles
+    ]
+    for noun, oid, sources in owners:
+        for i, s in enumerate(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"
+                    f"{noun} {oid!r}: source[{i}] role {s.role!r} is not a known role id"
                 )
 
 

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/model.py

@@ -139,6 +139,29 @@ class Role:
     text: str
 
 
+@dataclass(frozen=True)
+class Principle:
+    """A founding product commitment — the vision, held as given rather than validated.
+
+    In the logic-system reading prodc already uses (a need is a proposition, a proof its
+    answer-with-evidence, an ``assumption`` a conjecture taken on faith *to be tested*), a principle
+    differs in intent: it is a chosen frame the product is built on, not a bet pending validation.
+    It is what decides between clients who want opposite things — a need that contradicts it is
+    withdrawn ``out_of_scope`` citing it (:attr:`Withdrawal.principle`).
+
+    Principles are discovered, not decreed: ``sources`` keeps the signals that surfaced one (often a
+    client), and ``revised_at`` dates its latest statement. A decision taken under an older version
+    of the principle is flagged for re-review when the principle is revised — the ripple. A separate noun
+    (like :class:`Role`), not a Need marker: a principle is a stance, not what a person wants, so it
+    never enters coverage, the plan, or the opinion check.
+    """
+
+    id: str
+    text: str
+    revised_at: str | None = None  # ISO date the principle was last stated or revised
+    sources: tuple[Source, ...] = ()  # the signals that surfaced it — provenance, not validation
+
+
 class AttestationKind(StrEnum):
     """Who reviewed the warrant — a ladder of strength, human strongest (cf. SourceKind)."""
 
@@ -185,11 +208,14 @@ class Withdrawal:
     Unlike a draft (staged, not yet decided), a withdrawal is a decision *against*: the need is
     taken off the active board and out of coverage, with its ``reason``, ``date`` and ``kind`` kept
     on the record as the durable trace (``prodc show`` still renders it). Reinstate to put it back.
+    ``principle`` names the :class:`Principle` the decision rests on (typically for ``out_of_scope``), so a
+    later revision of that principle can flag this decision for re-review.
     """
 
     reason: str
     date: str
     kind: WithdrawalKind = WithdrawalKind.WONT_DO
+    principle: str | None = None  # id of the Principle this decision rests on
 
 
 @dataclass(frozen=True)
@@ -345,6 +371,7 @@ class Model:
     goals: tuple[Goal, ...] = ()
     releases: tuple[Release, ...] = ()  # in declared order = ship sequence
     roles: tuple[Role, ...] = ()  # the roles needs' `who` play (#52)
+    principles: tuple[Principle, ...] = ()  # the product vision, held as given
     argument: tuple[ArgNode, ...] = ()  # the GSN assurance graph (#28)
 
 

{prodc-0.3.78 → prodc-0.3.79}/src/prodc/status.py

@@ -23,6 +23,7 @@ from .model import (
     Need,
     NeedResult,
     NeedState,
+    Principle,
     ProofState,
     Release,
     Role,
@@ -631,6 +632,53 @@ def role_report(
     return coverage, unroled
 
 
+@dataclass(frozen=True)
+class PrincipleReport:
+    """One principle and the decisions that rest on it — the ripple, made visible."""
+
+    principle: Principle
+    declined: tuple[Need, ...]  # needs withdrawn citing this principle
+    stale: tuple[Need, ...]  # of those, decided before the principle's latest revision — re-review
+
+
+def _decided_before(decided: str, revised: str | None) -> bool:
+    """True when a decision dated ``decided`` predates a principle revised on ``revised``.
+
+    Both are ISO dates. An undated principle, or a malformed date on either side, is never stale —
+    there is no revision to compare against, and the loader does not own date format here.
+    """
+    if revised is None:
+        return False
+    try:
+        return date.fromisoformat(decided) < date.fromisoformat(revised)
+    except ValueError:
+        return False
+
+
+def principle_report(needs: list[Need], principles: list[Principle]) -> list[PrincipleReport]:
+    """Each declared principle with the needs withdrawn under it, and which of those are stale.
+
+    Reads the *whole* need list, withdrawn needs included — a declined need is off the board, so
+    the board-filtered list would hide exactly what this reports. A decision is stale when the
+    withdrawal is dated before the principle's ``revised_at``: the frame it was judged against has
+    changed since, so it comes back up for re-review. Records-only — prodc flags, the PM re-decides.
+    """
+    by_principle: dict[str, list[Need]] = {a.id: [] for a in principles}
+    for n in needs:
+        if n.withdrawn is not None and n.withdrawn.principle in by_principle:
+            by_principle[n.withdrawn.principle].append(n)
+    out: list[PrincipleReport] = []
+    for a in principles:
+        declined = sorted(by_principle[a.id], key=lambda n: n.id)
+        stale = [
+            n
+            for n in declined
+            if n.withdrawn is not None and _decided_before(n.withdrawn.date, a.revised_at)
+        ]
+        out.append(PrincipleReport(a, tuple(declined), tuple(stale)))
+    return out
+
+
 @dataclass(frozen=True)
 class Handoff:
     """A derived step in a cross-role journey: one flow child hands off to the next (#52)."""