prodc 0.3.82__tar.gz → 0.3.83__tar.gz

{prodc-0.3.82 → prodc-0.3.83}/PKG-INFO

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

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

{prodc-0.3.82 → prodc-0.3.83}/src/prodc/cli/app.py

@@ -22,6 +22,7 @@ from .commands import (
     cmd_capture,
     cmd_diff,
     cmd_dupes,
+    cmd_guide,
     cmd_lint,
     cmd_plan,
     cmd_portfolio,
@@ -606,6 +607,18 @@ def main(argv: list[str] | None = None) -> int:
     ag.add_argument("--force", action="store_true", help="overwrite PATH if it already exists")
     ag.set_defaults(func=cmd_agent)
 
+    gd = sub.add_parser(
+        "guide", help="print prodc's human CLI guide (a short, scannable onboarding path)"
+    )
+    gd.add_argument(
+        "--write",
+        default=None,
+        metavar="PATH",
+        help="write the guide to PATH instead of stdout",
+    )
+    gd.add_argument("--force", action="store_true", help="overwrite PATH if it already exists")
+    gd.set_defaults(func=cmd_guide)
+
     df = sub.add_parser(
         "diff", help="diff the current board against a prior status --json snapshot"
     )

{prodc-0.3.82 → prodc-0.3.83}/src/prodc/cli/commands.py

@@ -1146,6 +1146,27 @@ def cmd_agent(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_guide(args: argparse.Namespace) -> int:
+    """Print prodc's human CLI guide (a short onboarding path), or write it to a file.
+
+    The human sibling of :func:`cmd_agent`: where `agent` ships an instruction set for a coding
+    agent, `guide` is the 60-second path a person reads to try prodc. Ships versioned with prodc;
+    `--write` drops it into a repo.
+    """
+    text = importlib.resources.files("prodc").joinpath("guide.md").read_text(encoding="utf-8")
+    if args.write:
+        dest = Path(args.write)
+        if dest.exists() and not args.force:
+            print(f"prodc: {dest} already exists (use --force to overwrite)", file=sys.stderr)
+            return 2
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(text, encoding="utf-8")
+        print(f"wrote prodc guide to {dest}")
+        return 0
+    print(text, end="")
+    return 0
+
+
 def cmd_suggest(args: argparse.Namespace) -> int:
     """Propose candidate proof locators for HOLE needs (or relink BROKEN ones) from the inventories (#54)."""
     loaded = load_or_report(args)

prodc-0.3.83/src/prodc/guide.md

@@ -0,0 +1,95 @@
+# prodc in 60 seconds
+
+prodc keeps product work in the repo, next to the code: who needs what, why, and the test that proves it is done. Plain YAML files, reviewed in pull requests like code.
+
+Try it now: `prodc status`
+
+## The two rules
+
+- **No evidence means it is an opinion.** A need backed only by your own guess still loads, but prodc marks it an opinion until a real user has said something. Example: "users want dark mode" with nobody quoted is an opinion.
+- **"Done" is a test, not a claim.** You do not mark a need done; you attach a proof that points into the real test suite. `prodc status` reads DELIVERED, HOLE, or BROKEN from it. Example: `proofs: ["pytest:tests/test_checkout.py::test_pays"]`.
+
+## Your first board
+
+Three files make a board.
+
+`prodc.toml`:
+
+```toml
+[prodc]
+needs = ["needs/*.yaml"]
+```
+
+`needs/needs.yaml`:
+
+```yaml
+needs:
+  - id: N-1
+    text: a buyer can pay for a cart
+    who: Dana
+    sources:
+      - kind: primary
+        who: Dana
+        quote: I could not check out on mobile
+    proofs: ["pytest:tests/test_checkout.py::test_pays"]
+```
+
+Then run `prodc status`. You get one board line per need, with its state and coverage.
+
+## Read the board
+
+| Command | Shows |
+|---|---|
+| `prodc status` | the whole board and coverage |
+| `prodc show <id>` | one need as a citable answer |
+| `prodc plan` | the backlog, ranked |
+| `prodc brief <client>` | what to ask a client before a call |
+
+## Record a need
+
+```
+prodc add need N-2 --text "a buyer can save a cart" --who you --kind assumption --file needs/needs.yaml
+```
+
+Warning: never record a `primary` source you invented. `primary` means a real user actually said it. Your own reasoning is `assumption`.
+
+## Prove a need
+
+A need moves HOLE, then PENDING, then DELIVERED as its proof comes true. For a HOLE, let prodc find the test:
+
+```
+prodc suggest N-1 --apply
+```
+
+## Gate it in CI
+
+```
+prodc lint --strict
+```
+
+Exit codes are the contract: 0 is clean, 1 is a gate failed (a broken proof or a must-have opinion), 2 is a usage or config error.
+
+## Stuck? A gap is a valid answer
+
+A HOLE (no proof yet) or an opinion (no evidence yet) is honest output, not a failure. Leave it visible. Never attach a fake proof to turn a row green.
+
+## Cheat sheet
+
+| To | Run |
+|---|---|
+| see the board | `prodc status` |
+| read one need | `prodc show <id>` |
+| rank the backlog | `prodc plan` |
+| prep a client call | `prodc brief <client>` |
+| add a need | `prodc add need <id> --text "..." --who you --kind assumption --file <f>` |
+| attach evidence | `prodc capture <id> --kind primary --who <person> --date <ISO> --quote "..."` |
+| attach a proof | `prodc suggest <id> --apply` |
+| decide against a need | `prodc withdraw <id> --reason "..."` |
+| gate in CI | `prodc lint --strict` |
+
+## Going further
+
+- The vision, held as given: `prodc add principle <id> --text "..."`
+- How a need gets built (the chosen solution): `prodc add decision <id> --text "..." --needs <ids>`
+- Full command list: `docs/commands.md`. The nouns: `docs/model.md`. Config: `docs/config.md`.
+- Teaching an AI agent to run prodc for you: `prodc agent`.

{prodc-0.3.82 → prodc-0.3.83}/tests/test_cli.py

@@ -513,3 +513,23 @@ def test_agent_write_creates_file_and_refuses_overwrite(
     assert main(["agent", "--write", str(dest)]) == 2
     assert "already exists" in capsys.readouterr().err
     assert main(["agent", "--write", str(dest), "--force"]) == 0
+
+
+def test_guide_prints_human_guide(capsys: pytest.CaptureFixture[str]) -> None:
+    code = main(["guide"])
+    out = capsys.readouterr().out
+    assert code == 0
+    assert "prodc in 60 seconds" in out
+    assert "The two rules" in out  # the human onboarding path is present
+
+
+def test_guide_write_creates_file_and_refuses_overwrite(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    dest = tmp_path / "sub" / "GUIDE.md"
+    assert main(["guide", "--write", str(dest)]) == 0
+    assert dest.exists() and "prodc" in dest.read_text(encoding="utf-8")
+    capsys.readouterr()
+    assert main(["guide", "--write", str(dest)]) == 2
+    assert "already exists" in capsys.readouterr().err
+    assert main(["guide", "--write", str(dest), "--force"]) == 0

{prodc-0.3.82 → prodc-0.3.83}/tests/test_models.py

@@ -11,11 +11,11 @@ from __future__ import annotations
 
 from dataclasses import dataclass, replace
 
-from musil import Action, Model, check
+from musil import Action, Model, check, explore, reaches
 
 from prodc.adapters import Adapter, ProofResult
-from prodc.model import Need, NeedState, ProofState
-from prodc.status import Resolver
+from prodc.model import Decision, Need, NeedState, ProofState, Withdrawal, board_needs
+from prodc.status import Resolver, active_decisions
 
 
 class _Stub:
@@ -211,6 +211,79 @@ FLOW_MODEL = Model(
 )
 
 
+# --- draft / withdrawn lifecycle (shared by Need and Decision) -----------------------
+# The board-membership state machine the writer verbs move an item through: a thing is staged
+# (draft), promoted (draft cleared), withdrawn (a decision against — off the board, record kept),
+# or reinstated. Every invariant derives from prodc's REAL rules (counts_toward_coverage /
+# board_needs / active_decisions), so a drift between this model and those rules is a failed check.
+# Note the asymmetry it pins down: coverage/board exclude a *withdrawn* item unconditionally, but a
+# *draft* only until promoted — and active_decisions excludes both.
+
+
+@dataclass(frozen=True)
+class Life:
+    draft: bool = True  # starts staged (proposed); promote clears it
+    withdrawn: bool = False
+
+
+def _life_actions() -> list[Action[Life]]:
+    return [
+        Action("promote", lambda s: s.draft and not s.withdrawn, lambda s: replace(s, draft=False)),
+        Action("withdraw", lambda s: not s.withdrawn, lambda s: replace(s, withdrawn=True)),
+        Action("reinstate", lambda s: s.withdrawn, lambda s: replace(s, withdrawn=False)),
+    ]
+
+
+def _w(s: Life) -> Withdrawal | None:
+    return Withdrawal(reason="r", date="2026-01-01") if s.withdrawn else None
+
+
+def _life_need(s: Life) -> Need:
+    return Need(id="n", text="x", draft=s.draft, withdrawn=_w(s))
+
+
+def _life_decision(s: Life) -> Decision:
+    return Decision(id="D", text="x", needs=("n",), draft=s.draft, withdrawn=_w(s))
+
+
+def _on_board(s: Life) -> bool:
+    return not s.draft and not s.withdrawn
+
+
+def _life_coverage_counts_iff_not_withdrawn(s: Life) -> bool:
+    """A leaf product need counts toward coverage exactly when not withdrawn — draft is orthogonal."""
+    return _life_need(s).counts_toward_coverage == (not s.withdrawn)
+
+
+def _life_board_default_excludes_draft_and_withdrawn(s: Life) -> bool:
+    """The counted board (no --include-drafts) holds the item iff it is neither draft nor withdrawn."""
+    on = _life_need(s).id in {n.id for n in board_needs([_life_need(s)], include_drafts=False)}
+    return on == _on_board(s)
+
+
+def _life_board_with_drafts_excludes_only_withdrawn(s: Life) -> bool:
+    """--include-drafts holds the item iff it is not withdrawn (a draft is kept, withdrawn never)."""
+    on = _life_need(s).id in {n.id for n in board_needs([_life_need(s)], include_drafts=True)}
+    return on == (not s.withdrawn)
+
+
+def _life_decision_active_iff_on_board(s: Life) -> bool:
+    """A decision is in force iff neither a draft nor withdrawn — stricter than need coverage."""
+    return (active_decisions([_life_decision(s)]) == [_life_decision(s)]) == _on_board(s)
+
+
+LIFE_MODEL = Model(
+    init=Life(),
+    actions=_life_actions(),
+    invariants={
+        "coverage-counts-iff-not-withdrawn": _life_coverage_counts_iff_not_withdrawn,
+        "board-default-excludes-draft-and-withdrawn": _life_board_default_excludes_draft_and_withdrawn,
+        "board-with-drafts-excludes-only-withdrawn": _life_board_with_drafts_excludes_only_withdrawn,
+        "decision-active-iff-on-board": _life_decision_active_iff_on_board,
+    },
+)
+
+
 # --- the gate ------------------------------------------------------------------------
 def test_leaf_lifecycle_safety() -> None:
     r = check(LEAF_MODEL)
@@ -222,6 +295,21 @@ def test_flow_rollup_safety() -> None:
     assert r.ok, f"{r.invariant}: {r.trace}"
 
 
+def test_lifecycle_safety() -> None:
+    r = check(LIFE_MODEL)
+    assert r.ok, f"{r.invariant}: {r.trace}"
+
+
+def test_lifecycle_board_always_recoverable() -> None:
+    """No reachable state is permanently stuck off the board: reinstate + promote always lead back.
+
+    The liveness counterpart to the safety invariants — it proves a withdrawn or staged item can
+    never get trapped off the active board (an item is never a one-way trip).
+    """
+    g = explore(LIFE_MODEL)
+    assert reaches(g, _on_board) == set(g.states)
+
+
 def test_checker_bites() -> None:
     """Guard against a vacuous suite: a knowingly false invariant must be caught."""
     bad = Model(