prodc 0.3.64__tar.gz → 0.3.65__tar.gz

{prodc-0.3.64 → prodc-0.3.65}/PKG-INFO

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

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

prodc-0.3.65/src/prodc/cli/__init__.py

@@ -0,0 +1,16 @@
+"""``prodc`` command line: the board (``status``) and its sibling commands.
+
+Prints the gap between needs and what the test suite proves, sorted by what needs
+attention first. Exit 1 on a BROKEN proof; ``--strict`` also on an opinion. A HOLE
+never fails — it is the honest gap you want people to keep writing.
+
+This package splits the former single ``cli`` module into ``app`` (argparse + dispatch),
+``commands`` (the handlers), ``render`` (text renderers), ``serialize`` (JSON), and
+``common`` (shared helpers). The public surface is unchanged: ``from prodc.cli import main``.
+"""
+
+from __future__ import annotations
+
+from .app import main
+
+__all__ = ["main"]

prodc-0.3.65/src/prodc/cli/app.py

@@ -0,0 +1,439 @@
+"""The argument parser and dispatch for ``prodc`` — one subparser per command.
+
+Builds the argparse tree, wires each subcommand to its handler in :mod:`prodc.cli.commands`,
+and runs it. ``main`` is the console entry point (``prodc.cli:main``), re-exported from the
+package ``__init__``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .. import __version__
+from .commands import (
+    cmd_accept,
+    cmd_add,
+    cmd_agent,
+    cmd_argument,
+    cmd_attest,
+    cmd_brief,
+    cmd_capture,
+    cmd_diff,
+    cmd_dupes,
+    cmd_lint,
+    cmd_plan,
+    cmd_portfolio,
+    cmd_recurrence,
+    cmd_report,
+    cmd_set,
+    cmd_show,
+    cmd_status,
+    cmd_suggest,
+    cmd_sync,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="prodc", description="Product management as code.")
+    parser.add_argument("--version", action="version", version=f"prodc {__version__}")
+    parser.add_argument(
+        "-C",
+        "--chdir",
+        metavar="DIR",
+        default=None,
+        help="run as if prodc was started in DIR (like `terraform -chdir`); must precede the command",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    st = sub.add_parser("status", help="show the needs board")
+    st.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    st.add_argument("--json", action="store_true", help="machine-readable output")
+    st.add_argument("--strict", action="store_true", help="also exit 1 on opinions")
+    st.add_argument("--wide", action="store_true", help="never truncate the need text")
+    st.add_argument(
+        "--client",
+        default=None,
+        metavar="ID",
+        help="scope the board + coverage to one client (its variants + baselines)",
+    )
+    st.add_argument(
+        "--goal",
+        default=None,
+        metavar="ID",
+        help="scope the board + coverage to the needs serving one goal",
+    )
+    st.add_argument(
+        "--columns",
+        default=None,
+        type=lambda s: [c.strip() for c in s.split(",")],
+        metavar="COLS",
+        help="flat table of just these columns, e.g. id,state,text,warrant",
+    )
+    st.add_argument("--only-must", action="store_true", help="show only must-have needs")
+    st.add_argument(
+        "--include-drafts",
+        action="store_true",
+        help="include draft (staged) needs in the board and coverage (#60)",
+    )
+    st.add_argument(
+        "--stale",
+        type=int,
+        default=None,
+        metavar="DAYS",
+        help="show only needs whose newest evidence (observed_at) is older than DAYS (#58)",
+    )
+    st.add_argument(
+        "--min-coverage",
+        type=float,
+        default=None,
+        metavar="FRAC",
+        help="gate: exit 1 if delivered/total < FRAC (0..1)",
+    )
+    st.add_argument(
+        "--max-dangling",
+        type=int,
+        default=None,
+        metavar="N",
+        help="gate: tolerate up to N broken locators instead of failing on any",
+    )
+    st.add_argument(
+        "--max-orphans",
+        type=int,
+        default=None,
+        metavar="N",
+        help="gate: exit 1 if more than N proof scenarios are claimed by no need",
+    )
+    st.set_defaults(func=cmd_status)
+
+    ln = sub.add_parser("lint", help="gate the board: fail on BROKEN proofs and must-opinions")
+    ln.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    ln.add_argument("--json", action="store_true", help="machine-readable output")
+    ln.add_argument("--strict", action="store_true", help="also fail on any hygiene warning")
+    ln.set_defaults(func=cmd_lint)
+
+    sh = sub.add_parser("show", help="show one need as a citable answer")
+    sh.add_argument("need_id", help="the need id to show, e.g. N-1")
+    sh.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    sh.add_argument("--json", action="store_true", help="machine-readable output")
+    sh.set_defaults(func=cmd_show)
+
+    br = sub.add_parser("brief", help="pre-meeting agenda for one client: open opinions and HOLEs")
+    br.add_argument("client", help="the client/variant id to brief, e.g. acme")
+    br.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    br.add_argument("--json", action="store_true", help="machine-readable output")
+    br.set_defaults(func=cmd_brief)
+
+    pl = sub.add_parser("plan", help="ranked backlog from must + state + evidence (+ importance)")
+    pl.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    pl.add_argument("--json", action="store_true", help="machine-readable output")
+    pl.add_argument(
+        "--include-drafts", action="store_true", help="include draft (staged) needs (#60)"
+    )
+    pl.set_defaults(func=cmd_plan)
+
+    ar = sub.add_parser("argument", help="show the GSN assurance graph and its defects")
+    ar.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    ar.add_argument("--json", action="store_true", help="machine-readable output")
+    ar.add_argument("--strict", action="store_true", help="exit 1 if the graph has any defect")
+    ar.set_defaults(func=cmd_argument)
+
+    st2 = sub.add_parser("set", help="set or append one field on a need (writes YAML)")
+    st2.add_argument("need_id", help="the need id to edit, e.g. N-1")
+    st2.add_argument("assignment", help="key=value, or key+=value to append (proofs/children)")
+    st2.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    st2.add_argument("--json", action="store_true", help="machine-readable output")
+    st2.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diff, don't write"
+    )
+    st2.add_argument(
+        "--expect-sha",
+        default=None,
+        metavar="SHA256",
+        help="refuse if the file's content hash differs (optimistic lock)",
+    )
+    st2.set_defaults(func=cmd_set)
+
+    ad = sub.add_parser(
+        "add", help="create a new agent-authored need, or declare a role (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(
+        "--who",
+        default=None,
+        help="need only: the author (recorded on the provenance source); required for `add need`",
+    )
+    ad.add_argument(
+        "--kind",
+        choices=["assumption", "secondary", "internal", "proxy"],
+        default="assumption",
+        help="need only: provenance source kind — assumption (default) or secondary; never "
+        "primary for an agent (internal/proxy accepted as aliases for assumption)",
+    )
+    ad.add_argument(
+        "--file",
+        required=True,
+        metavar="PATH",
+        help="prodc file to write into, relative to the config (must match a glob)",
+    )
+    ad.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    ad.add_argument("--json", action="store_true", help="machine-readable output")
+    ad.add_argument(
+        "--strict-dupes",
+        action="store_true",
+        help="refuse to add if a possible duplicate exists (#55)",
+    )
+    ad.add_argument(
+        "--no-dupe-check", action="store_true", help="skip the duplicate check entirely (#55)"
+    )
+    ad.add_argument(
+        "--draft",
+        action="store_true",
+        help="stage as a draft: loads but stays off the counted board until promoted (#60)",
+    )
+    ad.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diff, don't write"
+    )
+    ad.add_argument(
+        "--expect-sha",
+        default=None,
+        metavar="SHA256",
+        help="refuse if the file's content hash differs (optimistic lock)",
+    )
+    ad.set_defaults(func=cmd_add)
+
+    cp = sub.add_parser("capture", help="append a source (evidence) to an existing need")
+    cp.add_argument("need_id", help="the need id to add evidence to")
+    cp.add_argument(
+        "--kind",
+        required=True,
+        choices=[
+            "primary",
+            "secondary",
+            "assumption",
+            "interview",
+            "artifact",
+            "proxy",
+            "internal",
+        ],
+        help="source kind, strongest first: primary > secondary > assumption "
+        "(interview/artifact/proxy/internal accepted as aliases)",
+    )
+    cp.add_argument("--who", default=None, help="the person the evidence came from")
+    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)")
+    cp.add_argument(
+        "--observed-at",
+        default=None,
+        metavar="ISO",
+        help="when this evidence was recorded/refreshed (default: today) (#58)",
+    )
+    cp.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    cp.add_argument("--json", action="store_true", help="machine-readable output")
+    cp.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diff, don't write"
+    )
+    cp.add_argument(
+        "--expect-sha",
+        default=None,
+        metavar="SHA256",
+        help="refuse if the file's content hash differs (optimistic lock)",
+    )
+    cp.set_defaults(func=cmd_capture)
+
+    at = sub.add_parser("attest", help="record a human or AI review of a need's warrant (#13)")
+    at.add_argument("need_id", help="the need id being attested")
+    at.add_argument("--by", required=True, help="who reviewed it — a person's name or a model id")
+    at.add_argument("--date", required=True, help="when (ISO, e.g. 2026-10-05)")
+    at.add_argument("--ai", action="store_true", help="the reviewer is an AI model, not a human")
+    at.add_argument(
+        "--verdict", default=None, help="the reviewer's conclusion, e.g. pass/concerns/fail"
+    )
+    at.add_argument("--comment", default=None, help="the review's feedback, kept on the record")
+    at.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    at.add_argument("--json", action="store_true", help="machine-readable output")
+    at.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diff, don't write"
+    )
+    at.add_argument(
+        "--expect-sha",
+        default=None,
+        metavar="SHA256",
+        help="refuse if the file's content hash differs (optimistic lock)",
+    )
+    at.set_defaults(func=cmd_attest)
+
+    ac = sub.add_parser("accept", help="record a human acceptance pass (accept proof) on a need")
+    ac.add_argument("need_id", help="the need id that was accepted")
+    ac.add_argument("--who", required=True, help="who accepted it")
+    ac.add_argument("--date", required=True, help="when (ISO, e.g. 2026-10-05)")
+    ac.add_argument("--revoke", action="store_true", help="remove this accept proof instead")
+    ac.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    ac.add_argument("--json", action="store_true", help="machine-readable output")
+    ac.add_argument(
+        "--dry-run", action="store_true", help="validate and show the diff, don't write"
+    )
+    ac.add_argument(
+        "--expect-sha",
+        default=None,
+        metavar="SHA256",
+        help="refuse if the file's content hash differs (optimistic lock)",
+    )
+    ac.set_defaults(func=cmd_accept)
+
+    pf = sub.add_parser("portfolio", help="roll up many repos into one scoreboard")
+    pf.add_argument("configs", nargs="+", metavar="PRODC_TOML", help="one or more prodc.toml paths")
+    pf.add_argument("--json", action="store_true", help="machine-readable output")
+    pf.set_defaults(func=cmd_portfolio)
+
+    rc = sub.add_parser(
+        "recurrence", help="baselines shared across clients; --suggest proposes unlinked groups"
+    )
+    rc.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    rc.add_argument("--json", action="store_true", help="machine-readable output")
+    rc.add_argument(
+        "--suggest",
+        action="store_true",
+        help="propose unlinked cross-client needs that could share a baseline (#56)",
+    )
+    rc.add_argument(
+        "--threshold",
+        type=float,
+        default=None,
+        metavar="FRAC",
+        help="similarity for --suggest (0..1); overrides [lint].duplicate_threshold",
+    )
+    rc.add_argument(
+        "--apply",
+        action="store_true",
+        help="with --suggest: link each group to a shared baseline (reuses a client-less "
+        "member, or creates one with --baseline-id/--file) (#56)",
+    )
+    rc.add_argument(
+        "--baseline-id",
+        default=None,
+        metavar="ID",
+        help="id for a baseline to create when a group has no client-less member",
+    )
+    rc.add_argument(
+        "--file",
+        default=None,
+        metavar="PATH",
+        help="file to write a created baseline into (must match a [prodc].needs glob)",
+    )
+    rc.add_argument(
+        "--dry-run", action="store_true", help="with --apply: validate and show diffs, don't write"
+    )
+    rc.set_defaults(func=cmd_recurrence)
+
+    sg = sub.add_parser(
+        "suggest", help="propose candidate proofs for HOLE needs from adapter inventories (#54)"
+    )
+    sg.add_argument("need_id", nargs="?", default=None, help="only this need (default: all HOLEs)")
+    sg.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    sg.add_argument("--json", action="store_true", help="machine-readable output")
+    sg.add_argument(
+        "--min-score",
+        type=float,
+        default=0.3,
+        metavar="FRAC",
+        help="minimum text similarity to suggest (0..1, default 0.3)",
+    )
+    sg.add_argument("--top", type=int, default=3, metavar="N", help="max suggestions per need")
+    sg.add_argument(
+        "--kind", default=None, metavar="ADAPTER", help="only suggest from this adapter name"
+    )
+    sg.add_argument(
+        "--apply",
+        action="store_true",
+        help="write the best suggestion per need as a proof (#54); honours --min-score",
+    )
+    sg.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="with --apply: validate and show the diff, don't write",
+    )
+    sg.set_defaults(func=cmd_suggest)
+
+    du = sub.add_parser("dupes", help="list candidate duplicate need pairs by text similarity")
+    du.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    du.add_argument("--json", action="store_true", help="machine-readable output")
+    du.add_argument(
+        "--threshold",
+        type=float,
+        default=None,
+        metavar="FRAC",
+        help="similarity to flag (0..1); overrides [lint].duplicate_threshold",
+    )
+    du.set_defaults(func=cmd_dupes)
+
+    rp = sub.add_parser(
+        "report", help="render the board as a shareable document (markdown, or an interactive HTML)"
+    )
+    rp.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    rp.add_argument(
+        "--format",
+        choices=["md", "html"],
+        default="md",
+        help="md (default) or html — a self-contained, interactive, read-only viewer (#79)",
+    )
+    rp.add_argument(
+        "--output",
+        "-o",
+        default=None,
+        metavar="PATH",
+        help="write the report to PATH (e.g. status.md / status.html) instead of stdout",
+    )
+    rp.add_argument(
+        "--client", default=None, metavar="ID", help="scope the report to one client (as `status`)"
+    )
+    rp.set_defaults(func=cmd_report)
+
+    sy = sub.add_parser(
+        "sync",
+        help="run lifecycle callbacks for needs whose state changed since the last sync (#71)",
+    )
+    sy.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    sy.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="show which transitions would fire callbacks; don't run them or write the ledger",
+    )
+    sy.set_defaults(func=cmd_sync)
+
+    ag = sub.add_parser(
+        "agent",
+        help="print prodc's agent playbook (teach a coding agent to run prodc as the project's PM)",
+    )
+    ag.add_argument(
+        "--write",
+        default=None,
+        metavar="PATH",
+        help="write the playbook to PATH instead of stdout (e.g. AGENTS.md)",
+    )
+    ag.add_argument("--force", action="store_true", help="overwrite PATH if it already exists")
+    ag.set_defaults(func=cmd_agent)
+
+    df = sub.add_parser(
+        "diff", help="diff the current board against a prior status --json snapshot"
+    )
+    df.add_argument("snapshot", help="path to a saved `prodc status --json` file")
+    df.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
+    df.add_argument("--json", action="store_true", help="machine-readable output")
+    df.set_defaults(func=cmd_diff)
+
+    args = parser.parse_args(argv)
+    if args.chdir is not None:
+        try:
+            os.chdir(args.chdir)
+        except OSError as exc:
+            print(f"prodc: cannot chdir to {args.chdir}: {exc}", file=sys.stderr)
+            return 2
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())