prodc 0.3.78__tar.gz → 0.3.80__tar.gz

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.3.78"
+version = "0.3.80"
 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.80}/src/prodc/agent.md

@@ -72,8 +72,11 @@ 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#…`) |
+| mark two needs as opposing each other | `prodc set <id> contradicts+=<other-id>` — symmetric (declare once); `lint` flags a pair left both-live (clients want opposite things and the vision has not decided), and `withdraw … --kind out_of_scope --principle <id>` resolves it |
 | 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` |

{prodc-0.3.78 → prodc-0.3.80}/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,11 +108,13 @@ 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
             ),
             "proofs": list(need.proofs),
+            "contradicts": list(need.contradicts),
             "detail": list(r.detail),
             "warnings": list(r.warnings),
             "attestation": (
@@ -152,12 +156,14 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
         "release": need.release,
         "product": need.product,
         "draft": need.draft,
+        "contradicts": list(need.contradicts),
         "answer": need.answer.value if need.answer else None,
         "withdrawn": (
             {
                 "reason": need.withdrawn.reason,
                 "date": need.withdrawn.date,
                 "kind": need.withdrawn.kind.value,
+                "principle": need.withdrawn.principle,
             }
             if need.withdrawn
             else None
@@ -202,6 +208,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 +225,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 +247,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.80}/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.80}/src/prodc/cli/commands.py

@@ -36,8 +36,10 @@ from ..status import (
     RelinkSuggestion,
     applicable_needs,
     argument_defects,
+    contradictions,
     evidence_age_days,
     importance_revisit_due,
+    principle_report,
     proof_suggestions,
     recurrence,
     relink_suggestions,
@@ -49,6 +51,7 @@ from ..writer import (
     WriteError,
     accept,
     add_need,
+    add_principle,
     add_proof,
     add_role,
     attest,
@@ -57,6 +60,7 @@ from ..writer import (
     link_variant_group,
     reinstate,
     relink_proof,
+    revise_principle,
     set_field,
     set_importance,
     withdraw,
@@ -83,6 +87,7 @@ from .render import (
     render_out_of_scope,
     render_plan,
     render_portfolio,
+    render_principles,
     render_recurrence,
     render_releases,
     render_roles,
@@ -232,6 +237,28 @@ 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"
+                )
+    # Unresolved contradiction: two needs oppose each other yet BOTH are still live — the product
+    # vision has not decided between them. A warning on both sides (withdraw one out_of_scope citing
+    # the principle that decides, or reconcile them).
+    for c in contradictions(needs):
+        if not c.unresolved:
+            continue
+        for near, far in ((c.a, c.b), (c.b, c.a)):
+            if near.id in by_id:
+                by_id[near.id].warnings.append(
+                    f"unresolved contradiction with {far.id} — both live, the vision has not "
+                    "decided yet (withdraw one out_of_scope citing the principle, or reconcile)"
+                )
     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 +345,7 @@ def cmd_status(args: argparse.Namespace) -> int:
                 role_cov,
                 unroled,
                 hos,
+                principles=board.principles,
             )
         )
     else:
@@ -350,6 +378,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 +509,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 +624,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 +654,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.80}/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:
@@ -320,6 +340,8 @@ def render_show(r: NeedResult, importance_label: str | None = None) -> str:
         lines.append("  sources: (none — opinion)")
     if need.children:
         lines.append(f"  children: {', '.join(need.children)}")
+    if need.contradicts:
+        lines.append(f"  contradicts: {', '.join(need.contradicts)}")
     if need.seam:
         lines.append(f"  seam: {', '.join(need.seam)}")
     if need.proofs:

{prodc-0.3.78 → prodc-0.3.80}/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.80}/src/prodc/loader.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 import datetime
 from collections.abc import Callable
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import cast
 
@@ -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
@@ -241,6 +244,10 @@ def _need(
         _as_str(d, f"{where}.not_variant_of[{i}]")
         for i, d in enumerate(_as_list(tbl.get("not_variant_of"), f"{where}.not_variant_of"))
     )
+    contradicts = tuple(
+        _as_str(c, f"{where}.contradicts[{i}]")
+        for i, c in enumerate(_as_list(tbl.get("contradicts"), f"{where}.contradicts"))
+    )
     if children and proofs:
         raise LoaderError(
             f"{where} ({nid}): a flow (need with children) proves its steps via the "
@@ -271,6 +278,7 @@ def _need(
         product=product,
         not_duplicate_of=not_duplicate_of,
         not_variant_of=not_variant_of,
+        contradicts=contradicts,
         importance_set_at=importance_set_at,
         draft=draft,
         draft_added=draft_added,
@@ -304,6 +312,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 +358,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 +399,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 +414,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 +426,7 @@ def load(config: Config) -> Model:
         "goal": {},
         "release": {},
         "role": {},
+        "principle": {},
         "argument node": {},
     }
     for pattern in config.need_globs:
@@ -407,19 +436,29 @@ 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_contradicts(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)
+    acc.needs = _symmetrize_contradicts(acc.needs)
     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 +478,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"
                 )
 
 
@@ -479,6 +521,37 @@ def _check_children(needs: list[Need]) -> None:
                 raise LoaderError(f"need {need.id!r}: child {cid!r} is not a known need id")
 
 
+def _check_contradicts(needs: list[Need]) -> None:
+    """Every id in a need's ``contradicts`` must name a known need, and never the need itself."""
+    known = {n.id for n in needs}
+    for need in needs:
+        for cid in need.contradicts:
+            if cid == need.id:
+                raise LoaderError(f"need {need.id!r}: contradicts itself")
+            if cid not in known:
+                raise LoaderError(f"need {need.id!r}: contradicts {cid!r} is not a known need id")
+
+
+def _symmetrize_contradicts(needs: list[Need]) -> list[Need]:
+    """Close the ``contradicts`` relation symmetrically: if A declares B, B contradicts A too.
+
+    The file stays single-declaration — declare the edge once, so the comment-safe writer never has
+    to touch two needs — but the loaded model carries the full symmetric neighbour set on both
+    needs, so every reader (show, lint, the JSON payload) sees the one relation. Run after
+    :func:`_check_contradicts`, so every target id is known.
+    """
+    edges: dict[str, set[str]] = {n.id: set(n.contradicts) for n in needs}
+    for n in needs:
+        for t in n.contradicts:
+            edges[t].add(n.id)
+    return [
+        replace(n, contradicts=tuple(sorted(edges[n.id])))
+        if edges[n.id] != set(n.contradicts)
+        else n
+        for n in needs
+    ]
+
+
 def _check_variants(needs: list[Need]) -> None:
     """Every ``variant_of`` must point at a known baseline need (one that is not itself a variant)."""
     by_id = {n.id: n for n in needs}