prodc 0.4.3__tar.gz → 0.4.4__tar.gz

{prodc-0.4.3 → prodc-0.4.4}/PKG-INFO

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

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

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/cli/app.py

@@ -181,6 +181,13 @@ def main(argv: list[str] | None = None) -> int:
         help="principle only: promote a need into a principle — copy its text (unless --text "
         "overrides) and its sources as the provenance that surfaced it; the need stays on the board",
     )
+    ad.add_argument(
+        "--scope",
+        default="product",
+        metavar="SCOPE",
+        help="principle only: its scope — product (default), design, visual, engineering; "
+        "must be declared in [principles].scopes",
+    )
     ad.add_argument(
         "--needs",
         default=None,

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/cli/commands.py

@@ -557,6 +557,7 @@ def cmd_add(args: argparse.Namespace) -> int:
                 text,
                 file=args.file,
                 revised_at=date.today().isoformat(),
+                scope=args.scope,
                 sources=sources,
                 expect_sha=args.expect_sha,
                 dry_run=args.dry_run,

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/cli/render.py

@@ -285,11 +285,12 @@ def render_principles(reports: list[PrincipleReport]) -> str:
     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):"]
+    out = ["\nprinciples (the 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}")
+        scope = "" if a.scope == "product" else f"[{a.scope}] "
+        out.append(f"  {a.id:<6} {scope}{rev}  {a.text}")
         if rep.declined:
             out.append(f"        declined: {', '.join(n.id for n in rep.declined)}")
         if rep.stale:

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/config.py

@@ -119,6 +119,7 @@ class Config:
     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
+    principle_scopes: tuple[str, ...] = ("product",)  # [principles].scopes — allowed scopes (#88)
 
     def importance_label(self, level: int | None) -> str | None:
         """The declared label for an importance level, or None if unset/undeclared (#59)."""
@@ -302,6 +303,15 @@ class Config:
 
         callbacks, callback_state_file = _callbacks(raw)
 
+        principles_tbl = _as_dict(raw.get("principles", {}), "[principles]")
+        if "scopes" in principles_tbl:
+            scopes = _as_str_list(principles_tbl["scopes"], "[principles].scopes")
+            if not scopes:
+                raise ConfigError("[principles].scopes must list at least one scope")
+            principle_scopes = tuple(scopes)
+        else:
+            principle_scopes = ("product",)
+
         return cls(
             root=root,
             need_globs=need_globs,
@@ -315,4 +325,5 @@ class Config:
             default_draft=default_draft,
             callbacks=callbacks,
             callback_state_file=callback_state_file,
+            principle_scopes=principle_scopes,
         )

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/loader.py

@@ -349,6 +349,7 @@ def _principle(raw: object, where: str) -> Principle:
     return Principle(
         id=_as_str(tbl.get("id"), f"{where}.id"),
         text=_as_str(tbl.get("text"), f"{where}.text"),
+        scope=_opt_str(tbl.get("scope"), f"{where}.scope") or "product",
         revised_at=_opt_str(tbl.get("revised_at"), f"{where}.revised_at"),
         sources=tuple(
             _source(s, f"{where}.sources[{i}]")
@@ -534,6 +535,7 @@ def load(config: Config) -> Model:
     _check_withdrawal_of(acc.needs)
     _check_source_roles(acc.needs, acc.principles, {p.id for p in acc.roles})
     _check_decisions(acc.decisions, {n.id for n in acc.needs}, {p.id for p in acc.principles})
+    _check_principle_scopes(acc.principles, config.principle_scopes)
     acc.needs = _symmetrize_contradicts(acc.needs)
     return Model(
         needs=tuple(acc.needs),
@@ -587,6 +589,17 @@ def _check_children(needs: list[Need]) -> None:
                 raise LoaderError(f"need {need.id!r}: child {c.id!r} is not a known need id")
 
 
+def _check_principle_scopes(principles: list[Principle], allowed: tuple[str, ...]) -> None:
+    """Every principle's ``scope`` must be one declared in ``[principles].scopes`` (#88)."""
+    allowed_set = set(allowed)
+    for p in principles:
+        if p.scope not in allowed_set:
+            raise LoaderError(
+                f"principle {p.id!r}: scope {p.scope!r} is not declared in "
+                f"[principles].scopes ({', '.join(allowed)})"
+            )
+
+
 def _check_withdrawal_of(needs: list[Need]) -> None:
     """A withdrawal's ``of`` must name a known need (never itself); required when kind is duplicate.
 

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/model.py

@@ -162,11 +162,18 @@ class Principle:
     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.
+    never enters coverage, the plan, or the opinion check — in every ``scope`` (#88).
+
+    ``scope`` says which kind of commitment it is — product, design, visual, engineering — so design,
+    visual and engineering principles live on the board beside product ones instead of in prose docs
+    and code comments, where a Decision or an ``out_of_scope`` withdrawal cannot cite them. The scope
+    must be one declared in ``[principles].scopes`` (default ``["product"]``); an undeclared scope is a
+    load error the author owns.
     """
 
     id: str
     text: str
+    scope: str = "product"  # product/design/visual/engineering — declared in [principles].scopes (#88)
     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
 

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/report.py

@@ -154,18 +154,18 @@ def render_markdown(
 
     if model.principles:
         out += [
-            "## Principles (the product vision — held as given)",
+            "## Principles (the vision — held as given)",
             "",
-            "| principle | stated | needs declined under it |",
-            "|---|---|---|",
+            "| principle | scope | stated | needs declined under it |",
+            "|---|---|---|---|",
         ]
         for rep in principle_report(list(model.needs), list(model.principles)):
             text = rep.principle.text.replace("|", "\\|")
             declined = ", ".join(n.id for n in rep.declined) or "—"
             stale = f" _(re-review {', '.join(n.id for n in rep.stale)})_" if rep.stale else ""
             out.append(
-                f"| {rep.principle.id}: {text} | {rep.principle.revised_at or '—'} "
-                f"| {declined}{stale} |"
+                f"| {rep.principle.id}: {text} | {rep.principle.scope} "
+                f"| {rep.principle.revised_at or '—'} | {declined}{stale} |"
             )
         out.append("")
 

{prodc-0.4.3 → prodc-0.4.4}/src/prodc/writer.py

@@ -914,6 +914,7 @@ def add_principle(
     *,
     file: str,
     revised_at: str,
+    scope: str = "product",
     sources: tuple[Source, ...] = (),
     expect_sha: str | None = None,
     dry_run: bool,
@@ -943,7 +944,10 @@ def add_principle(
         for a in principles
     ):
         raise WriteError(f"principle {principle_id!r} already exists in {target.name}")
-    entry: dict[str, object] = {"id": principle_id, "text": text, "revised_at": revised_at}
+    entry: dict[str, object] = {"id": principle_id, "text": text}
+    if scope != "product":
+        entry["scope"] = scope  # written only when non-default, to keep the common case clean
+    entry["revised_at"] = revised_at
     if sources:
         entry["sources"] = [_source_dict(s) for s in sources]
     principles.append(entry)

{prodc-0.4.3 → prodc-0.4.4}/tests/test_principles.py

@@ -132,6 +132,53 @@ principles:
         load(Config.load(_project(tmp_path, needs=needs)))
 
 
+# --- scope (#88) ------------------------------------------------------------
+
+_SCOPED_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+
+[principles]
+scopes = ["product", "visual", "engineering"]
+"""
+
+
+def test_principle_scope_defaults_to_product(tmp_path: Path) -> None:
+    needs = "principles:\n  - id: P-1\n    text: a principle\n"
+    model = load(Config.load(_project(tmp_path, needs=needs)))
+    assert model.principles[0].scope == "product"
+
+
+def test_declared_scope_loads(tmp_path: Path) -> None:
+    needs = "principles:\n  - id: P-1\n    text: colour is load-bearing\n    scope: visual\n"
+    model = load(Config.load(_project(tmp_path, toml=_SCOPED_TOML, needs=needs)))
+    assert model.principles[0].scope == "visual"
+
+
+def test_undeclared_scope_rejected(tmp_path: Path) -> None:
+    # default [principles].scopes is just ["product"], so "visual" is undeclared here.
+    needs = "principles:\n  - id: P-1\n    text: a principle\n    scope: visual\n"
+    with pytest.raises(LoaderError, match="scope 'visual' is not declared"):
+        load(Config.load(_project(tmp_path, needs=needs)))
+
+
+def test_add_principle_writes_scope(tmp_path: Path) -> None:
+    from prodc.writer import add_principle
+
+    cfg = Config.load(_project(tmp_path, toml=_SCOPED_TOML, needs="principles:\n  - id: P-0\n    text: seed\n"))
+    add_principle(
+        cfg,
+        "P-9",
+        "colour is load-bearing",
+        file="needs/a.yaml",
+        revised_at=date.today().isoformat(),
+        scope="visual",
+        dry_run=False,
+    )
+    model = load(cfg)
+    assert next(p for p in model.principles if p.id == "P-9").scope == "visual"
+
+
 # --- principle_report (declined / stale) ------------------------------------
 
 
@@ -275,7 +322,7 @@ def test_status_text_shows_principles_section(
 
     main(["status", "--config", str(_project(tmp_path))])
     out = capsys.readouterr().out
-    assert "principles (the product vision — held as given):" in out
+    assert "principles (the vision — held as given):" in out
     assert "P-1" in out and "revised 2026-10-15" in out
     assert "declined: N-7, N-9" in out
     assert "decided before the latest revision: N-7 — re-review" in out