prodc 0.3.82__tar.gz → 0.4.0__tar.gz

prodc-0.4.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes are documented here. Versioning is [SemVer](https://semver.org/).
+
+## [0.4.0] - 2026-10-16
+
+The OST is whole, and the board cannot lie.
+
+0.4 finishes the Opportunity-Solution Tree — a need now carries the solution
+chosen for it and the vision that solution rests on — and closes the gaps that
+let a board read greener than the evidence warranted.
+
+### Added
+
+- **Product principles** (`principles:`) — the product vision as a cited, rippling noun.
+  `add principle`, `revise principle`, and `add principle --from-need` (promote a need,
+  keeping its text and sources). An `out_of_scope` withdrawal must cite the principle it
+  rests on (`withdraw --principle`); revising a principle re-opens decisions taken under it.
+- **Decision noun** (`decisions:`) — the solution chosen for a need over the alternatives
+  rejected (OST, not an ADR). `add decision --needs … --alternative … --consequences …
+  --principles …`; `withdraw decision <id>` / `reinstate decision <id>` supersede and restore.
+  Lint flags an orphan decision (built on no need) and a stale one (its principle moved under it).
+- **`contradicts`** — a symmetric need↔need edge for two needs in tension; `lint` flags a pair
+  left both-live, because the vision has to decide between them.
+- **`prodc guide`** — a short human CLI onboarding guide, sibling to `prodc agent`;
+  `--write PATH` drops it into the repo.
+- **`report` renders Principles and Decisions** — both the markdown document and the
+  interactive HTML viewer now carry the two new sections.
+- **`status` shows unresolved contradictions** on the text board.
+
+### Changed (breaking)
+
+- **`Need.label` removed** (#52). Express it with a declared `role` + `client`:
+  John@Sincerely playing the `owner` role, not a free-text label. A board still carrying
+  `label:` fails to load with a message naming the replacement.
+  *Migration:* declare the role in `roles:`, set `role:` and `client:` on the need, drop `label:`.
+- **The GSN `argument` graph is cut.** Its job is absorbed by `claim` + `proofs` +
+  attestation: state the warrant as `need.claim`, prove it with proofs, review it with
+  `prodc attest`. A board carrying an `argument:` key fails to load with that guidance.
+  *Migration:* move each argument node's warrant onto the need's `claim`; delete `argument:`.
+- **Attestation `verdict` is an enum** — `pass` / `concerns` / `fail`. Only `pass` clears a
+  need; `concerns`, `fail`, or no verdict at all now warns, for a human and an AI reviewer
+  alike. This was the false-green bug: a recorded-but-not-passing review read as settled.
+  *Migration:* an attestation with no `verdict:` now warns — add `verdict: pass` where the
+  review did pass.
+- **A `duplicate` withdrawal must name its original** — `Withdrawal.of` is required when
+  `kind: duplicate` (`withdraw --of <id>`), so a duplicate always points at what it duplicates.
+
+> The `argument:` and `label:` load errors are tombstones for the 0.4 cutover; they are
+> scheduled for removal in 0.5.
+
+## [0.3.x]
+
+The 0.3 line turned prodc from a need-and-proof tracker into a full product-and-research
+board. Highlights, newest first:
+
+- **`prodc report`** — the board as a shareable document: a readable markdown file, or a
+  single self-contained, interactive, read-only HTML viewer (filter, search, regroup,
+  print to PDF) with no external assets.
+- **Research boards, unified** — no profile fork. An `answer` axis (settled questions with a
+  direction, including a settled-NO), a `need:` question→question DAG, and `evalgate` /
+  `citation` proof adapters, gated by claim-aware lint so one board holds product bets and
+  research questions the same way.
+- **Lifecycle callbacks** — `prodc sync` fires a configured command for each need whose state
+  changed since the last sync, ledger-tracked and retried on failure.
+- **Portfolio** — roll many boards into one scoreboard with a totals footer; discover boards
+  under a directory.
+- **Drafts and review** — staged needs (`draft: true`), `prodc review` to triage them, an
+  age gate, and portfolio exclusion.
+- **Withdrawal kinds** — `wont_do` / `out_of_scope` / `duplicate` on a decision-against a need.
+- **Source kinds** — the academic `primary` / `secondary` / `assumption` ladder; a need with
+  no primary or secondary source is an opinion. Old kind names still load, mapped on.
+- **Role noun** — a named function in the product's world; `who` + `client` is an instance of it.
+- **Importance rubric**, **free-form `description`**, and the **cli/ package split**.
+
+## [0.1.0]
+
+Initial release.

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

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

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

@@ -89,7 +89,7 @@ Read first, then act, then check.
 | act on a need going green (notify a tracker, etc.) | `prodc sync` — runs the `[callbacks]` commands for needs whose state changed since the last sync (`--dry-run` to preview) |
 | gate in CI | `prodc lint --strict` |
 
-Less often: `prodc argument` (the GSN assurance graph and its defects), `prodc portfolio <path>…`
+Less often: `prodc portfolio <path>…`
 (roll up many boards into one scoreboard + totals; a path is a prodc.toml or a dir to discover
 boards under), and `prodc diff <snapshot.json>` (what changed since a
 saved `status --json`). `prodc status` also takes `--goal <id>`, `--columns id,state,text,warrant`,

{prodc-0.3.82 → prodc-0.4.0}/src/prodc/board.py

@@ -94,7 +94,6 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
             "state": r.state.value,
             "must": need.must,
             "who": need.who or "(unassigned)",
-            "label": need.label,
             "client": need.client,
             "opinion": need.is_opinion,
             "warrant": strongest.value if strongest is not None else "opinion",
@@ -109,6 +108,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
                     "date": need.withdrawn.date,
                     "kind": need.withdrawn.kind.value,
                     "principle": need.withdrawn.principle,
+                    "of": need.withdrawn.of,
                 }
                 if need.withdrawn
                 else None
@@ -164,6 +164,7 @@ def need_payload(r: NeedResult, *, flavor: Literal["board", "html"] = "board") -
                 "date": need.withdrawn.date,
                 "kind": need.withdrawn.kind.value,
                 "principle": need.withdrawn.principle,
+                "of": need.withdrawn.of,
             }
             if need.withdrawn
             else None

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

@@ -16,12 +16,12 @@ from .commands import (
     cmd_accept,
     cmd_add,
     cmd_agent,
-    cmd_argument,
     cmd_attest,
     cmd_brief,
     cmd_capture,
     cmd_diff,
     cmd_dupes,
+    cmd_guide,
     cmd_lint,
     cmd_plan,
     cmd_portfolio,
@@ -143,12 +143,6 @@ def main(argv: list[str] | None = None) -> int:
     )
     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)")
@@ -316,7 +310,10 @@ def main(argv: list[str] | None = None) -> int:
     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"
+        "--verdict",
+        choices=["pass", "concerns", "fail"],
+        default=None,
+        help="the reviewer's conclusion; only pass clears the warrant (anything else warns)",
     )
     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")
@@ -353,7 +350,10 @@ def main(argv: list[str] | None = None) -> int:
     wd = sub.add_parser(
         "withdraw", help="record a decision against a need — withdrawn / won't-do (#74)"
     )
-    wd.add_argument("need_id", help="the need id to withdraw")
+    wd.add_argument("target", help="the need id to withdraw, or 'decision' to withdraw a decision")
+    wd.add_argument(
+        "decision_id", nargs="?", default=None, help="the decision id (when target is 'decision')"
+    )
     wd.add_argument(
         "--reason", required=True, help="why it was decided against (kept on the record)"
     )
@@ -365,6 +365,12 @@ 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(
+        "--of",
+        default=None,
+        metavar="ID",
+        help="the need this one duplicates (validated); required with --kind duplicate",
+    )
     wd.add_argument(
         "--principle",
         default=None,
@@ -388,7 +394,12 @@ def main(argv: list[str] | None = None) -> int:
     ri = sub.add_parser(
         "reinstate", help="remove a need's withdrawal, putting it back on the board (#74)"
     )
-    ri.add_argument("need_id", help="the need id to reinstate")
+    ri.add_argument(
+        "target", help="the need id to reinstate, or 'decision' to reinstate a decision"
+    )
+    ri.add_argument(
+        "decision_id", nargs="?", default=None, help="the decision id (when target is 'decision')"
+    )
     ri.add_argument("--config", default="prodc.toml", help="path to prodc.toml")
     ri.add_argument("--json", action="store_true", help="machine-readable output")
     ri.add_argument(
@@ -606,6 +617,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.4.0}/src/prodc/cli/commands.py

@@ -11,7 +11,7 @@ import argparse
 import importlib.resources
 import json
 import sys
-from dataclasses import asdict
+from dataclasses import asdict, replace
 from datetime import date
 from pathlib import Path
 from typing import cast
@@ -28,14 +28,13 @@ from ..dedup import (
     who_variants,
 )
 from ..loader import LoaderError, load
-from ..model import Model, Need, NeedResult, NeedState, board_needs
+from ..model import Need, NeedResult, NeedState, board_needs
 from ..report import render_markdown
 from ..report_html import render_html
 from ..status import (
     ProofSuggestion,
     RelinkSuggestion,
     applicable_needs,
-    argument_defects,
     contradictions,
     decisions_for,
     evidence_age_days,
@@ -63,11 +62,13 @@ from ..writer import (
     delete_need,
     link_variant_group,
     reinstate,
+    reinstate_decision,
     relink_proof,
     revise_principle,
     set_field,
     set_importance,
     withdraw,
+    withdraw_decision,
 )
 from .common import (
     RepoRow,
@@ -82,9 +83,9 @@ from .render import (
     COLUMNS,
     provenance_counts,
     render,
-    render_argument,
     render_brief,
     render_columns,
+    render_contradictions,
     render_decisions,
     render_goals,
     render_handoffs,
@@ -100,7 +101,6 @@ from .render import (
     summary_line,
 )
 from .serialize import (
-    argument_json,
     brief_json,
     dup_payload,
     plan_json,
@@ -178,20 +178,6 @@ def _annotate_draft_age_warnings(results: list[NeedResult], cfg: Config) -> None
             )
 
 
-def _annotate_label_deprecation(results: list[NeedResult]) -> None:
-    """Nudge needs still carrying the free-text `label` toward role + client (#52, deprecation).
-
-    Since Role (#52) carries the archetype and `client` the org, the per-need `label` is redundant —
-    "design partner, Sincerely" is `role` + `client`. Soft only: `label` is still parsed and still
-    renders; this flags it so a board can migrate off it before it is removed.
-    """
-    for r in results:
-        if r.need.label:
-            r.warnings.append(
-                f"'label' ({r.need.label!r}) is deprecated — express it with role + client (#52)"
-            )
-
-
 def _lint_errors(results: list[NeedResult]) -> list[str]:
     """Hard problems a lint gate fails on: a dangling proof, or a must-have with no evidence."""
     errors: list[str] = []
@@ -241,7 +227,6 @@ 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.
@@ -406,6 +391,9 @@ def cmd_status(args: argparse.Namespace) -> int:
             print(render_principles(board.principles))
         if model.decisions:
             print(render_decisions(list(model.decisions), needs=list(model.needs)))
+        unresolved = [c for c in contradictions(list(model.needs)) if c.unresolved]
+        if unresolved:
+            print(render_contradictions(unresolved))
         if orphan_map:
             print(render_orphans(orphan_map))
 
@@ -705,16 +693,32 @@ def cmd_withdraw(args: argparse.Namespace) -> int:
         return 2
     try:
         cfg = Config.load(cfg_path)
-        edit = withdraw(
-            cfg,
-            args.need_id,
-            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,
-        )
+        if args.target == "decision":
+            # noun-first: ids are unique per noun, so a need and a decision may share one — the
+            # noun disambiguates (matches `add decision` / `revise principle`).
+            if not args.decision_id:
+                print("prodc: withdraw decision needs a decision id", file=sys.stderr)
+                return 2
+            edit = withdraw_decision(
+                cfg,
+                args.decision_id,
+                reason=args.reason,
+                date=args.date or date.today().isoformat(),
+                expect_sha=args.expect_sha,
+                dry_run=args.dry_run,
+            )
+        else:
+            edit = withdraw(
+                cfg,
+                args.target,
+                reason=args.reason,
+                date=args.date or date.today().isoformat(),
+                kind=args.kind,
+                principle=args.principle,
+                of=args.of,
+                expect_sha=args.expect_sha,
+                dry_run=args.dry_run,
+            )
     except (ConfigError, WriteError) as exc:
         print(f"prodc: {exc}", file=sys.stderr)
         return 2
@@ -729,12 +733,23 @@ def cmd_reinstate(args: argparse.Namespace) -> int:
         return 2
     try:
         cfg = Config.load(cfg_path)
-        edit = reinstate(
-            cfg,
-            args.need_id,
-            expect_sha=args.expect_sha,
-            dry_run=args.dry_run,
-        )
+        if args.target == "decision":
+            if not args.decision_id:
+                print("prodc: reinstate decision needs a decision id", file=sys.stderr)
+                return 2
+            edit = reinstate_decision(
+                cfg,
+                args.decision_id,
+                expect_sha=args.expect_sha,
+                dry_run=args.dry_run,
+            )
+        else:
+            edit = reinstate(
+                cfg,
+                args.target,
+                expect_sha=args.expect_sha,
+                dry_run=args.dry_run,
+            )
     except (ConfigError, WriteError) as exc:
         print(f"prodc: {exc}", file=sys.stderr)
         return 2
@@ -921,15 +936,6 @@ def cmd_capture(args: argparse.Namespace) -> int:
     return emit_edit(edit, args.dry_run, args.json)
 
 
-def cmd_argument(args: argparse.Namespace) -> int:
-    """Show the GSN assurance graph and its defects (unsupported claim, dangling assumption)."""
-    loaded = load_or_report(args)
-    if loaded is None:
-        return 2
-    _cfg, model = loaded
-    defects = argument_defects(list(model.argument))
-    print(argument_json(model, defects) if args.json else render_argument(model, defects))
-    return 1 if (args.strict and defects) else 0
 
 
 def _repo_row(config_path: str) -> RepoRow:
@@ -1041,14 +1047,10 @@ def cmd_report(args: argparse.Namespace) -> int:
         return 2
     cfg, model = loaded
     if args.client:
+        # replace keeps every other noun (principles, decisions, …); a hand-rolled Model(...)
+        # silently dropped them, which breaks the moment the report renders them (#0.4).
         scoped = applicable_needs(list(model.needs), args.client)
-        model = Model(
-            needs=tuple(scoped),
-            goals=model.goals,
-            releases=model.releases,
-            roles=model.roles,
-            argument=model.argument,
-        )
+        model = replace(model, needs=tuple(scoped))
     if args.format == "html":
         text = render_html(cfg, model, client=args.client, rev=git_rev(cfg.root))
     else:
@@ -1146,6 +1148,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.82 → prodc-0.4.0}/src/prodc/cli/render.py

@@ -14,7 +14,6 @@ from ..board import warrant as _warrant
 from ..model import (
     Decision,
     Goal,
-    Model,
     Need,
     NeedResult,
     NeedState,
@@ -23,6 +22,7 @@ from ..model import (
     ears_shape,
 )
 from ..status import (
+    Contradiction,
     Handoff,
     PrincipleReport,
     Recurrence,
@@ -139,11 +139,9 @@ def render(results: list[NeedResult], wide: bool = False) -> str:
     ]
     for who in sorted(groups):
         rs = sorted(groups[who], key=state_priority)
-        label = next((x.need.label for x in rs if x.need.label), None)
         counts = {s: sum(1 for r in rs if r.state is s) for s in NeedState}
         head = "   ".join(f"{counts[s]} {_LABEL[s]}" for s in NeedState if counts[s])
-        title = f"{who}" + (f" ({label})" if label else "")
-        out.append(f"\n{title}    {head}")
+        out.append(f"\n{who}    {head}")
         out.append(f"    {_provenance_line(rs)}\n")
         for r in rs:
             out.append(
@@ -289,6 +287,14 @@ def render_principles(reports: list[PrincipleReport]) -> str:
     return "\n".join(out)
 
 
+def render_contradictions(contras: list[Contradiction]) -> str:
+    """Unresolved contradictions on the board: two needs in tension the vision has not decided."""
+    out = ["\ncontradictions (two needs in tension — the vision has not decided):"]
+    for c in contras:
+        out.append(f"  {c.a.id} vs {c.b.id}    {c.a.text[:32]}  /  {c.b.text[:32]}")
+    return "\n".join(out)
+
+
 def render_decisions(decisions: list[Decision], needs: list[Need]) -> str:
     """The solution chosen for each need (OST), what it rejected, and the needs it serves.
 
@@ -319,7 +325,7 @@ def render_show(
 ) -> str:
     """One need as a citable answer — the artifact you drop into a thread."""
     need = r.need
-    who = (need.who + (f" ({need.label})" if need.label else "")) if need.who else "(unassigned)"
+    who = need.who or "(unassigned)"
     who += f" — {need.role}" if need.role else ""
     nm = f"  {r.delivered}/{r.total}" if r.total else ""
     lines = [
@@ -332,7 +338,8 @@ def render_show(
         lines.append(f"  answer: {need.answer.value}")
     if need.withdrawn:
         w = need.withdrawn
-        tag = "" if w.kind.value == "wont_do" else f" [{w.kind.value}]"
+        of = f" of {w.of}" if w.of else ""
+        tag = "" if w.kind.value == "wont_do" else f" [{w.kind.value}{of}]"
         per = f" per {w.principle}" if w.principle else ""
         lines.append(f"  withdrawn{tag}{per}: {w.reason} ({w.date})")
     if need.description:
@@ -450,21 +457,6 @@ def render_plan(
     return "\n".join(out)
 
 
-def render_argument(model: Model, defects: list[str]) -> str:
-    out = [f"argument — GSN graph: {len(model.argument)} node(s), {len(defects)} defect(s)"]
-    for node in model.argument:
-        links = ""
-        if node.supported_by:
-            links += f"  ←{','.join(node.supported_by)}"
-        if node.in_context_of:
-            links += f"  ⊙{','.join(node.in_context_of)}"
-        about = f"  [{node.about}]" if node.about else ""
-        out.append(f"  {node.id:<12} {node.kind.value:<13} {node.text[:44]}{about}{links}")
-    for d in defects:
-        out.append(f"  ⚠ {d}")
-    return "\n".join(out)
-
-
 def render_portfolio(rows: list[RepoRow], totals: PortfolioTotals | None = None) -> str:
     if not rows:
         return "  no boards found"

{prodc-0.3.82 → prodc-0.4.0}/src/prodc/cli/serialize.py

@@ -12,7 +12,7 @@ import json
 from ..board import need_payload
 from ..board import warrant as _warrant
 from ..dedup import DupPair, VariantGroup
-from ..model import Decision, Goal, Model, NeedResult, NeedState, Release, Role
+from ..model import Decision, Goal, NeedResult, NeedState, Release, Role
 from ..status import Handoff, PrincipleReport, Recurrence, Summary, rank
 from .common import brief_open
 
@@ -147,7 +147,6 @@ def show_json(r: NeedResult, decisions: list[Decision] | None = None) -> str:
     payload = need_payload(r)  # the shared core — never drifts from the board
     payload.update(
         {
-            "label": need.label,
             "decisions": [_decision_payload(d) for d in (decisions or [])],
             "sources": [
                 {
@@ -223,26 +222,6 @@ def plan_json(
     )
 
 
-def argument_json(model: Model, defects: list[str]) -> str:
-    return json.dumps(
-        {
-            "nodes": [
-                {
-                    "id": n.id,
-                    "kind": n.kind.value,
-                    "text": n.text,
-                    "supported_by": list(n.supported_by),
-                    "in_context_of": list(n.in_context_of),
-                    "about": n.about,
-                }
-                for n in model.argument
-            ],
-            "defects": defects,
-        },
-        indent=2,
-    )
-
-
 def variant_payload(g: VariantGroup) -> dict[str, object]:
     return {
         "score": round(g.score, 4),

prodc-0.4.0/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`.