prodc 0.4.6__tar.gz → 0.4.7__tar.gz

prodc-0.4.7/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: prodc
+Version: 0.4.7
+Summary: Product management as code: roles, flows, and features traced to evidence.
+Project-URL: Homepage, https://gitlab.com/cardona-oss/prodc
+Project-URL: Repository, https://gitlab.com/cardona-oss/prodc
+Project-URL: Changelog, https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://cardona-oss.gitlab.io/prodc/
+Author-email: Jorge Cardona <jorgeecardona@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: pyyaml>=6
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# prodc
+
+[![PyPI](https://img.shields.io/pypi/v/prodc)](https://pypi.org/project/prodc/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE)
+
+Product management as code: the *needs* your product exists to meet, each traced to the evidence a real user gave for it and the test that proves it is delivered. For teams that keep product work in the repo, next to the code, and want a tool to check it holds together.
+
+prodc reads plain YAML files and your test suite and shows you the gaps. It does not call a model, host a UI, or replace your tracker. Two rules carry it:
+
+1. **A need with no evidence is an opinion.** Write down who asked — an interview quote, a ticket, an email — or prodc flags the need as an opinion, because that is what it is until someone outside the room has asked.
+2. **"Done" is a claim your tests back.** You never mark a need delivered. You attach a *proof* (a locator into your test suite), and `prodc status` resolves it: DELIVERED, PENDING, HOLE (an honest gap), or BROKEN (points at nothing). The state is read from the repo, not remembered from a standup.
+
+## Install
+
+```bash
+pip install prodc          # or: uv add prodc
+```
+
+Python 3.12+. The only runtime dependency is PyYAML.
+
+## Quickstart
+
+Three files. The first tells prodc where to look, the second holds what people need, the third is a test you have probably already written.
+
+`prodc.toml`
+
+```toml
+[prodc]
+needs = ["needs/*.yaml"]
+
+[proofs.web]
+kind = "gherkin"
+paths = ["features/*.feature"]
+delivered = ["@implemented"]
+pending = ["@pending"]
+```
+
+`needs/jordan.yaml`
+
+```yaml
+who: jordan
+needs:
+  - id: N-1
+    text: "see which orders are past due at a glance"
+    must: true
+    sources:
+      - kind: primary
+        who: Jordan
+        date: 2026-09-20
+        quote: "I lose the past-due ones in the list"
+    proofs:
+      - "web:orders.feature#Past due orders are highlighted"
+
+  - id: N-2
+    text: "export the day's delivery run sheet"
+    sources:
+      - kind: secondary
+        locator: issues.md#N-2
+        date: 2026-09-21
+
+  - id: N-3
+    text: "implement a settings page"
+```
+
+`features/orders.feature`
+
+```gherkin
+Feature: Orders board
+
+  @implemented
+  Scenario: Past due orders are highlighted
+    Given an order whose due date has passed
+    When I open the orders board
+    Then the order is highlighted as past due
+```
+
+Run the board (output trimmed; the real one also carries a legend and phrasing hints):
+
+```text
+$ prodc status
+gaps: 2 HOLE  ·  1 opinion    coverage 1/3 (33%)
+
+jordan    1 DELIVERED   2 HOLE
+    provenance: 1 primary  ·  1 secondary  ·  0 assumption  ·  1 opinion
+
+      N-2  HOLE            export the day's delivery run sheet          secondary
+      N-3  HOLE            implement a settings page                    opinion
+       ⚠ text may be a solution in disguise (starts with 'implement')
+  !!  N-1  DELIVERED* 1/1  see which orders are past due at a glance    primary:Jordan
+       ⚠ DELIVERED on an unattested proof link — warrant not reviewed
+```
+
+N-1 is DELIVERED because a tagged scenario proves it (the `*` means declared by tag, no test results loaded yet). N-2 has evidence but no proof: a HOLE. N-3 has neither: an opinion.
+
+Now close the loop from the command line. Each write command rewrites one YAML file, re-validates the whole model, and prints the diff.
+
+```bash
+# trace the opinion to evidence
+prodc capture N-3 --kind primary --who Jordan --date 2026-10-01 \
+    --quote "I keep changing the printer in three places"
+
+# add the scenario to your suite, tagged @pending until it is green:
+#     @pending
+#     Scenario: Export the run sheet
+# then point the need at it:
+prodc set N-2 proofs+="web:orders.feature#Export the run sheet"
+
+prodc status      # gaps: 1 PENDING · 1 HOLE   — the scenario exists, so N-2 is PENDING, not BROKEN
+                  # (skip writing the scenario and the proof points at nothing: BROKEN, lint exits 1)
+prodc lint        # CI gate: exit 1 on a BROKEN proof or a must-have with no evidence
+```
+
+Change a scenario title without updating the need and the proof turns BROKEN; `prodc lint` exits 1. That is the whole idea: the board cannot drift from the code.
+
+## Why prodc
+
+**Versus Jira, Linear, and other trackers.** A tracker records work items and a status someone set by hand. prodc records *needs* and computes their status from the tests. It has no assignees, sprints, comments, or notifications, and it is not trying to. Keep the tracker for the work; keep prodc for the question "did a real user ask for this, and does a test prove it?" The two connect at the edges: a need's source can be a ticket locator (checked read-only against GitLab with `[sources.<name>] kind = "gitlab"`), a proof can be resolved by any script you point at a tracker (`kind = "command"`), and `prodc sync` fires a hook when a need changes state.
+
+**Versus a PRD in Notion or a wiki.** A document says what should be true; nothing checks it later. prodc's files are validated on every load (ids, cross-references, source hygiene), linted in CI, and reviewed in merge requests like code. "Is this done?" is answered by `prodc show N-1`, not by finding the right page.
+
+**Versus plain YAML in the repo.** You could keep this structure by hand. prodc adds the schema, the proof resolution against real test suites, the evidence ladder, the lint, and the write-back commands that keep the files consistent.
+
+**What it does not do.** It does not run your tests, call an LLM, or ping a tracker on its own. It does not model the full discovery loop (opportunity-solution-tree restructuring, parallel solution testing); it records needs, the evidence under them, and the decisions taken on them.
+
+## Key features
+
+- **Evidence ladder.** A source is `primary` (the user's own words), `secondary` (a report, a
+  ticket, an internal doc), or `assumption` (a guess). With neither primary nor secondary, the need
+  is an opinion: `lint` fails a must-have opinion, `status --strict` fails on any.
+- **Proofs resolve against the repo.** Adapters for Gherkin scenarios and tags, pytest node ids,
+  file existence, human sign-off, prototypes, citations, eval metric gates, external results files,
+  and a generic `command` hook. Feed it cucumber-json or junit XML and declared states become real.
+- **Five states, honest semantics.** DELIVERED, PENDING, HOLE, BROKEN, UNRESOLVED. A HOLE is never
+  a failure; BROKEN always is; a proof in an absent sibling repo is UNRESOLVED, not BROKEN.
+- **Flows.** A need with `children` rolls them up, with `seam` proofs for the behaviour between
+  steps. Any BROKEN child breaks the flow; a flow is DELIVERED only when every child and seam is
+  green.
+- **The roll-up is machine-checked.** `tests/test_models.py` builds a
+  [musil](https://pypi.org/project/musil/) model of the lifecycle and explores every reachable
+  state against the real resolver, so the documented invariants cannot drift from the code.
+- **Write-back that respects your files.** `set`, `capture`, `accept`, `attest`, `withdraw`, `add`
+  splice one need's block back into the original YAML, keeping other comments. All take `--dry-run`
+  and `--expect-sha`.
+- **Boards for humans.** `status`, `show`, `brief`, `plan`, `report --format html` (a self-contained
+  interactive viewer), `portfolio`, and `diff` against a snapshot. The read commands (`status`,
+  `lint`, `show`, `brief`, `plan`, `diff`, `portfolio`, `dupes`, `recurrence`, `suggest`, `review`)
+  take `--json`; exit codes are fixed (0 ok, 1 gate failed, 2 config or load error).
+
+prodc also models goals, releases, roles, principles, decisions, attestations, withdrawals and
+settled answers, and ships hygiene commands (`dupes`, `recurrence`, `suggest`); the
+[docs](https://cardona-oss.gitlab.io/prodc/) have the full surface.
+
+## Use it with a coding agent
+
+prodc ships a playbook that teaches an agent to act as the project's product manager: read the board, capture evidence with honest provenance, find proofs, gate before a handoff. An agent may record `assumption` or `secondary` sources; `primary` is reserved for a real user's own words.
+
+```bash
+prodc agent >> AGENTS.md     # or: prodc agent --write AGENTS.md
+prodc guide                  # the short human onboarding guide
+```
+
+## Links
+
+- Repository: <https://gitlab.com/cardona-oss/prodc>
+- PyPI: <https://pypi.org/project/prodc/>
+- Docs: <https://cardona-oss.gitlab.io/prodc/> — [Quickstart](https://cardona-oss.gitlab.io/prodc/quickstart/), [Commands](https://cardona-oss.gitlab.io/prodc/commands/), [Model](https://cardona-oss.gitlab.io/prodc/model/), [Config](https://cardona-oss.gitlab.io/prodc/config/), [Lifecycle](https://cardona-oss.gitlab.io/prodc/lifecycle/)
+- Changelog: [CHANGELOG.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md)
+
+`AGENTS.md` holds build and test instructions for coding agents working on prodc itself.
+
+## License
+
+MIT. See [LICENSE](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE).

prodc-0.4.7/README.md

@@ -0,0 +1,173 @@
+# prodc
+
+[![PyPI](https://img.shields.io/pypi/v/prodc)](https://pypi.org/project/prodc/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE)
+
+Product management as code: the *needs* your product exists to meet, each traced to the evidence a real user gave for it and the test that proves it is delivered. For teams that keep product work in the repo, next to the code, and want a tool to check it holds together.
+
+prodc reads plain YAML files and your test suite and shows you the gaps. It does not call a model, host a UI, or replace your tracker. Two rules carry it:
+
+1. **A need with no evidence is an opinion.** Write down who asked — an interview quote, a ticket, an email — or prodc flags the need as an opinion, because that is what it is until someone outside the room has asked.
+2. **"Done" is a claim your tests back.** You never mark a need delivered. You attach a *proof* (a locator into your test suite), and `prodc status` resolves it: DELIVERED, PENDING, HOLE (an honest gap), or BROKEN (points at nothing). The state is read from the repo, not remembered from a standup.
+
+## Install
+
+```bash
+pip install prodc          # or: uv add prodc
+```
+
+Python 3.12+. The only runtime dependency is PyYAML.
+
+## Quickstart
+
+Three files. The first tells prodc where to look, the second holds what people need, the third is a test you have probably already written.
+
+`prodc.toml`
+
+```toml
+[prodc]
+needs = ["needs/*.yaml"]
+
+[proofs.web]
+kind = "gherkin"
+paths = ["features/*.feature"]
+delivered = ["@implemented"]
+pending = ["@pending"]
+```
+
+`needs/jordan.yaml`
+
+```yaml
+who: jordan
+needs:
+  - id: N-1
+    text: "see which orders are past due at a glance"
+    must: true
+    sources:
+      - kind: primary
+        who: Jordan
+        date: 2026-09-20
+        quote: "I lose the past-due ones in the list"
+    proofs:
+      - "web:orders.feature#Past due orders are highlighted"
+
+  - id: N-2
+    text: "export the day's delivery run sheet"
+    sources:
+      - kind: secondary
+        locator: issues.md#N-2
+        date: 2026-09-21
+
+  - id: N-3
+    text: "implement a settings page"
+```
+
+`features/orders.feature`
+
+```gherkin
+Feature: Orders board
+
+  @implemented
+  Scenario: Past due orders are highlighted
+    Given an order whose due date has passed
+    When I open the orders board
+    Then the order is highlighted as past due
+```
+
+Run the board (output trimmed; the real one also carries a legend and phrasing hints):
+
+```text
+$ prodc status
+gaps: 2 HOLE  ·  1 opinion    coverage 1/3 (33%)
+
+jordan    1 DELIVERED   2 HOLE
+    provenance: 1 primary  ·  1 secondary  ·  0 assumption  ·  1 opinion
+
+      N-2  HOLE            export the day's delivery run sheet          secondary
+      N-3  HOLE            implement a settings page                    opinion
+       ⚠ text may be a solution in disguise (starts with 'implement')
+  !!  N-1  DELIVERED* 1/1  see which orders are past due at a glance    primary:Jordan
+       ⚠ DELIVERED on an unattested proof link — warrant not reviewed
+```
+
+N-1 is DELIVERED because a tagged scenario proves it (the `*` means declared by tag, no test results loaded yet). N-2 has evidence but no proof: a HOLE. N-3 has neither: an opinion.
+
+Now close the loop from the command line. Each write command rewrites one YAML file, re-validates the whole model, and prints the diff.
+
+```bash
+# trace the opinion to evidence
+prodc capture N-3 --kind primary --who Jordan --date 2026-10-01 \
+    --quote "I keep changing the printer in three places"
+
+# add the scenario to your suite, tagged @pending until it is green:
+#     @pending
+#     Scenario: Export the run sheet
+# then point the need at it:
+prodc set N-2 proofs+="web:orders.feature#Export the run sheet"
+
+prodc status      # gaps: 1 PENDING · 1 HOLE   — the scenario exists, so N-2 is PENDING, not BROKEN
+                  # (skip writing the scenario and the proof points at nothing: BROKEN, lint exits 1)
+prodc lint        # CI gate: exit 1 on a BROKEN proof or a must-have with no evidence
+```
+
+Change a scenario title without updating the need and the proof turns BROKEN; `prodc lint` exits 1. That is the whole idea: the board cannot drift from the code.
+
+## Why prodc
+
+**Versus Jira, Linear, and other trackers.** A tracker records work items and a status someone set by hand. prodc records *needs* and computes their status from the tests. It has no assignees, sprints, comments, or notifications, and it is not trying to. Keep the tracker for the work; keep prodc for the question "did a real user ask for this, and does a test prove it?" The two connect at the edges: a need's source can be a ticket locator (checked read-only against GitLab with `[sources.<name>] kind = "gitlab"`), a proof can be resolved by any script you point at a tracker (`kind = "command"`), and `prodc sync` fires a hook when a need changes state.
+
+**Versus a PRD in Notion or a wiki.** A document says what should be true; nothing checks it later. prodc's files are validated on every load (ids, cross-references, source hygiene), linted in CI, and reviewed in merge requests like code. "Is this done?" is answered by `prodc show N-1`, not by finding the right page.
+
+**Versus plain YAML in the repo.** You could keep this structure by hand. prodc adds the schema, the proof resolution against real test suites, the evidence ladder, the lint, and the write-back commands that keep the files consistent.
+
+**What it does not do.** It does not run your tests, call an LLM, or ping a tracker on its own. It does not model the full discovery loop (opportunity-solution-tree restructuring, parallel solution testing); it records needs, the evidence under them, and the decisions taken on them.
+
+## Key features
+
+- **Evidence ladder.** A source is `primary` (the user's own words), `secondary` (a report, a
+  ticket, an internal doc), or `assumption` (a guess). With neither primary nor secondary, the need
+  is an opinion: `lint` fails a must-have opinion, `status --strict` fails on any.
+- **Proofs resolve against the repo.** Adapters for Gherkin scenarios and tags, pytest node ids,
+  file existence, human sign-off, prototypes, citations, eval metric gates, external results files,
+  and a generic `command` hook. Feed it cucumber-json or junit XML and declared states become real.
+- **Five states, honest semantics.** DELIVERED, PENDING, HOLE, BROKEN, UNRESOLVED. A HOLE is never
+  a failure; BROKEN always is; a proof in an absent sibling repo is UNRESOLVED, not BROKEN.
+- **Flows.** A need with `children` rolls them up, with `seam` proofs for the behaviour between
+  steps. Any BROKEN child breaks the flow; a flow is DELIVERED only when every child and seam is
+  green.
+- **The roll-up is machine-checked.** `tests/test_models.py` builds a
+  [musil](https://pypi.org/project/musil/) model of the lifecycle and explores every reachable
+  state against the real resolver, so the documented invariants cannot drift from the code.
+- **Write-back that respects your files.** `set`, `capture`, `accept`, `attest`, `withdraw`, `add`
+  splice one need's block back into the original YAML, keeping other comments. All take `--dry-run`
+  and `--expect-sha`.
+- **Boards for humans.** `status`, `show`, `brief`, `plan`, `report --format html` (a self-contained
+  interactive viewer), `portfolio`, and `diff` against a snapshot. The read commands (`status`,
+  `lint`, `show`, `brief`, `plan`, `diff`, `portfolio`, `dupes`, `recurrence`, `suggest`, `review`)
+  take `--json`; exit codes are fixed (0 ok, 1 gate failed, 2 config or load error).
+
+prodc also models goals, releases, roles, principles, decisions, attestations, withdrawals and
+settled answers, and ships hygiene commands (`dupes`, `recurrence`, `suggest`); the
+[docs](https://cardona-oss.gitlab.io/prodc/) have the full surface.
+
+## Use it with a coding agent
+
+prodc ships a playbook that teaches an agent to act as the project's product manager: read the board, capture evidence with honest provenance, find proofs, gate before a handoff. An agent may record `assumption` or `secondary` sources; `primary` is reserved for a real user's own words.
+
+```bash
+prodc agent >> AGENTS.md     # or: prodc agent --write AGENTS.md
+prodc guide                  # the short human onboarding guide
+```
+
+## Links
+
+- Repository: <https://gitlab.com/cardona-oss/prodc>
+- PyPI: <https://pypi.org/project/prodc/>
+- Docs: <https://cardona-oss.gitlab.io/prodc/> — [Quickstart](https://cardona-oss.gitlab.io/prodc/quickstart/), [Commands](https://cardona-oss.gitlab.io/prodc/commands/), [Model](https://cardona-oss.gitlab.io/prodc/model/), [Config](https://cardona-oss.gitlab.io/prodc/config/), [Lifecycle](https://cardona-oss.gitlab.io/prodc/lifecycle/)
+- Changelog: [CHANGELOG.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md)
+
+`AGENTS.md` holds build and test instructions for coding agents working on prodc itself.
+
+## License
+
+MIT. See [LICENSE](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE).

{prodc-0.4.6 → prodc-0.4.7}/examples/quickstart/needs/jordan.yaml

@@ -1,5 +1,4 @@
 who: jordan
-label: "design partner"
 needs:
   - id: N-1
     text: "see which orders are past due at a glance"

{prodc-0.4.6 → prodc-0.4.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "prodc"
-version = "0.4.6"
+version = "0.4.7"
 description = "Product management as code: roles, flows, and features traced to evidence."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -32,9 +32,10 @@ docs = [
 ]
 
 [project.urls]
-Homepage = "https://gitlab.com/jorgeecardona/prodc"
-Repository = "https://gitlab.com/jorgeecardona/prodc"
-Changelog = "https://gitlab.com/jorgeecardona/prodc/-/blob/main/CHANGELOG.md"
+Homepage = "https://gitlab.com/cardona-oss/prodc"
+Repository = "https://gitlab.com/cardona-oss/prodc"
+Changelog = "https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md"
+Documentation = "https://cardona-oss.gitlab.io/prodc/"
 
 [build-system]
 requires = ["hatchling"]

{prodc-0.4.6 → prodc-0.4.7}/src/prodc/cli/commands.py

@@ -39,6 +39,7 @@ from ..status import (
     contradictions,
     decisions_for,
     evidence_age_days,
+    flow_step_warnings,
     importance_revisit_due,
     orphaned_decisions,
     principle_report,
@@ -298,6 +299,9 @@ def cmd_lint(args: argparse.Namespace) -> int:
         | {n.client for n in needs if n.client is not None}
     )
     warnings += tag_warnings(needs, structural_ids, cfg.duplicate_threshold)
+    # Flow step hygiene (#90): once [flows].steps declares a vocabulary, grade each journey's
+    # shape — never-terminal, out-of-order, mixed bare/stepped. Silent when no vocab is declared.
+    warnings += flow_step_warnings(needs, cfg.flow_steps)
     if args.json:
         print(
             json.dumps(

{prodc-0.4.6 → prodc-0.4.7}/src/prodc/config.py

@@ -120,6 +120,16 @@ class Config:
     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)
+    flow_steps: tuple[str, ...] = ()  # [flows].steps — ordered step vocab; () = undeclared (#90)
+
+    @property
+    def terminal_step(self) -> str | None:
+        """The step that ends a journey: the last declared step, or None when no vocab (#90).
+
+        The single definition of 'terminal' — status/lint read it here, never recompute
+        ``flow_steps[-1]`` elsewhere. Order in ``[flows].steps`` *is* the journey.
+        """
+        return self.flow_steps[-1] if self.flow_steps else None
 
     def importance_label(self, level: int | None) -> str | None:
         """The declared label for an importance level, or None if unset/undeclared (#59)."""
@@ -312,6 +322,17 @@ class Config:
         else:
             principle_scopes = ("product",)
 
+        flows_tbl = _as_dict(raw.get("flows", {}), "[flows]")
+        if "steps" in flows_tbl:
+            steps = _as_str_list(flows_tbl["steps"], "[flows].steps")
+            if not steps:
+                raise ConfigError("[flows].steps must list at least one step")
+            if len(set(steps)) != len(steps):
+                raise ConfigError("[flows].steps must not repeat a step (order is its rank)")
+            flow_steps = tuple(steps)
+        else:
+            flow_steps = ()
+
         return cls(
             root=root,
             need_globs=need_globs,
@@ -326,4 +347,5 @@ class Config:
             callbacks=callbacks,
             callback_state_file=callback_state_file,
             principle_scopes=principle_scopes,
+            flow_steps=flow_steps,
         )

{prodc-0.4.6 → prodc-0.4.7}/src/prodc/loader.py

@@ -554,6 +554,7 @@ def load(config: Config) -> Model:
     _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)
+    _check_flow_steps(acc.needs, config.flow_steps)
     acc.needs = _symmetrize_contradicts(acc.needs)
     return Model(
         needs=tuple(acc.needs),
@@ -618,6 +619,27 @@ def _check_principle_scopes(principles: list[Principle], allowed: tuple[str, ...
             )
 
 
+def _check_flow_steps(needs: list[Need], allowed: tuple[str, ...]) -> None:
+    """Every flow edge's ``step`` must be one declared in ``[flows].steps`` (#90).
+
+    Membership is integrity, not judgment — a mis-spelled step (``conlcude``) is a typo, the
+    same severity as an undeclared principle scope, so it is a hard load error. Because the
+    writer re-loads and reverts on ``LoaderError``, this also refuses to *write* a bad step.
+    Skipped entirely when no vocabulary is declared: a bare step stays free text, as it was
+    before this. Order and completeness are the lint's job, not the loader's.
+    """
+    if not allowed:
+        return
+    allowed_set = set(allowed)
+    for need in needs:
+        for c in need.children:
+            if c.step is not None and c.step not in allowed_set:
+                raise LoaderError(
+                    f"need {need.id!r}: child {c.id!r} step {c.step!r} is not declared in "
+                    f"[flows].steps ({', '.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.6 → prodc-0.4.7}/src/prodc/status.py

@@ -911,6 +911,51 @@ def flow_orphan_warnings(needs: list[Need]) -> set[str]:
     return {n.id for n in needs if not n.children and n.id not in in_a_flow}
 
 
+def flow_step_warnings(needs: list[Need], steps: tuple[str, ...]) -> list[tuple[str, str]]:
+    """Judgment-level hygiene on a flow's steps, once a ``[flows].steps`` vocabulary exists (#90).
+
+    Opt-in: silent when no vocabulary is declared — a board with no steps has no journey to
+    grade. Membership (a step word that isn't in the vocab) is the loader's hard error; this
+    catches the *shape* of the journey, keyed by flow id, as warnings:
+
+    - **never terminal**: a flow with stepped edges but none carrying the terminal step — the
+      journey never ends (Patton: the story must end). The message names the configured word.
+    - **out of order**: stepped edges whose rank decreases along ``children`` — the map runs
+      backwards. Warned once per flow.
+    - **mixed bare/stepped**: a flow where some edges carry a step and some don't — a use case
+      with a hole, which would otherwise pass clean.
+
+    A flow with zero stepped edges is exempt: it's a plain flow, not a use case (#90), and
+    warning it would punish every existing board the moment a vocabulary is declared.
+    """
+    if not steps:
+        return []
+    terminal = steps[-1]
+    rank = {s: i for i, s in enumerate(steps)}
+    out: list[tuple[str, str]] = []
+    for flow in needs:
+        if not flow.children:
+            continue
+        stepped = [c for c in flow.children if c.step is not None]
+        if not stepped:
+            continue  # a plain flow, not a use case — exempt
+        if len(stepped) != len(flow.children):
+            bare = next(c.id for c in flow.children if c.step is None)
+            out.append((flow.id, f"edge {bare!r} has no step while siblings do — a use case with a hole"))
+        if not any(c.step == terminal for c in stepped):
+            out.append(
+                (
+                    flow.id,
+                    f"no edge carries the terminal step {terminal!r} — the journey never ends; "
+                    "add it or drop the steps",
+                )
+            )
+        ranks = [rank[c.step] for c in stepped if c.step in rank]
+        if any(b < a for a, b in pairwise(ranks)):
+            out.append((flow.id, "steps run out of order — reorder children or re-step the edges"))
+    return out
+
+
 def shared_proof_warnings(results: list[NeedResult]) -> dict[str, str]:
     """Flag a need whose *every* proof is also claimed by another need (#45).
 

prodc-0.4.7/tests/test_flowsteps.py

@@ -0,0 +1,172 @@
+"""Flow step vocabulary (#90 follow-up): [flows].steps config, the load-time membership
+error, and the flow_step_warnings hygiene lint (never-terminal / out-of-order / mixed)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from prodc.config import Config, ConfigError
+from prodc.loader import LoaderError, load
+from prodc.model import Child, Need
+from prodc.status import flow_step_warnings
+
+_TOML = """
+[prodc]
+needs = ["needs/*.yaml"]
+
+[flows]
+steps = ["trigger", "act", "conclude"]
+"""
+
+
+def _project(tmp_path: Path, toml: str = _TOML, needs: str = "needs: []\n") -> Path:
+    (tmp_path / "needs").mkdir(parents=True, exist_ok=True)
+    (tmp_path / "prodc.toml").write_text(toml, encoding="utf-8")
+    (tmp_path / "needs" / "a.yaml").write_text(needs, encoding="utf-8")
+    return tmp_path / "prodc.toml"
+
+
+# --- config (#90) -----------------------------------------------------------
+
+
+def test_flow_steps_default_is_empty_and_terminal_none(tmp_path: Path) -> None:
+    cfg = Config.load(_project(tmp_path, toml="[prodc]\nneeds = [\"needs/*.yaml\"]\n"))
+    assert cfg.flow_steps == ()
+    assert cfg.terminal_step is None  # no vocab → nothing is terminal
+
+
+def test_flow_steps_parsed_ordered_and_terminal_is_last(tmp_path: Path) -> None:
+    cfg = Config.load(_project(tmp_path))
+    assert cfg.flow_steps == ("trigger", "act", "conclude")
+    assert cfg.terminal_step == "conclude"  # last entry, the single definition of terminal
+
+
+def test_flow_steps_empty_list_rejected(tmp_path: Path) -> None:
+    toml = "[prodc]\nneeds = [\"needs/*.yaml\"]\n\n[flows]\nsteps = []\n"
+    with pytest.raises(ConfigError, match=r"\[flows\].steps must list at least one step"):
+        Config.load(_project(tmp_path, toml=toml))
+
+
+def test_flow_steps_duplicate_rejected(tmp_path: Path) -> None:
+    toml = "[prodc]\nneeds = [\"needs/*.yaml\"]\n\n[flows]\nsteps = [\"act\", \"act\"]\n"
+    with pytest.raises(ConfigError, match="must not repeat a step"):
+        Config.load(_project(tmp_path, toml=toml))
+
+
+# --- loader membership = hard error (#90) -----------------------------------
+
+
+def test_undeclared_step_is_load_error(tmp_path: Path) -> None:
+    needs = """
+needs:
+  - id: F-1
+    text: a flow
+    children: [{id: US-1, step: conlcude}]
+  - id: US-1
+    text: a step
+"""
+    with pytest.raises(LoaderError, match="step 'conlcude' is not declared in"):
+        load(Config.load(_project(tmp_path, needs=needs)))
+
+
+def test_declared_step_loads(tmp_path: Path) -> None:
+    needs = """
+needs:
+  - id: F-1
+    text: a flow
+    children: [{id: US-1, step: trigger}, {id: US-2, step: conclude}]
+  - id: US-1
+    text: a
+  - id: US-2
+    text: b
+"""
+    model = load(Config.load(_project(tmp_path, needs=needs)))
+    flow = next(n for n in model.needs if n.id == "F-1")
+    assert [c.step for c in flow.children] == ["trigger", "conclude"]
+
+
+def test_no_vocab_lets_any_step_pass(tmp_path: Path) -> None:
+    toml = "[prodc]\nneeds = [\"needs/*.yaml\"]\n"
+    needs = """
+needs:
+  - id: F-1
+    text: a flow
+    children: [{id: US-1, step: whatever}]
+  - id: US-1
+    text: a
+"""
+    model = load(Config.load(_project(tmp_path, toml=toml, needs=needs)))
+    assert model.needs[0].children[0].step == "whatever"  # free text, unchecked
+
+
+# --- lint: shape of the journey (#90) ---------------------------------------
+
+_STEPS = ("trigger", "act", "conclude")
+
+
+def test_lint_silent_without_vocabulary() -> None:
+    needs = [Need(id="F-1", text="f", children=(Child("A", "trigger"),)), Need(id="A", text="a")]
+    assert flow_step_warnings(needs, ()) == []
+
+
+def test_lint_exempts_flow_with_no_stepped_edges() -> None:
+    needs = [Need(id="F-1", text="f", children=(Child("A"), Child("B")))]
+    assert flow_step_warnings(needs, _STEPS) == []  # a plain flow, not a use case
+
+
+def test_lint_warns_when_no_terminal_step() -> None:
+    needs = [Need(id="F-1", text="f", children=(Child("A", "trigger"), Child("B", "act")))]
+    warns = flow_step_warnings(needs, _STEPS)
+    assert any(nid == "F-1" and "terminal step 'conclude'" in m for nid, m in warns)
+
+
+def test_lint_terminal_step_names_the_configured_word() -> None:
+    needs = [Need(id="F-1", text="f", children=(Child("A", "start"),))]
+    warns = flow_step_warnings(needs, ("start", "done"))
+    assert any("terminal step 'done'" in m for _, m in warns)  # not hardcoded "conclude"
+
+
+def test_lint_warns_on_out_of_order_steps() -> None:
+    needs = [
+        Need(id="F-1", text="f", children=(Child("A", "act"), Child("B", "trigger"), Child("C", "conclude")))
+    ]
+    warns = flow_step_warnings(needs, _STEPS)
+    assert any("out of order" in m for _, m in warns)
+
+
+def test_lint_warns_on_mixed_bare_and_stepped() -> None:
+    needs = [
+        Need(id="F-1", text="f", children=(Child("A", "trigger"), Child("B"), Child("C", "conclude")))
+    ]
+    warns = flow_step_warnings(needs, _STEPS)
+    assert any("has no step while siblings do" in m for _, m in warns)
+
+
+def test_lint_clean_journey_is_silent() -> None:
+    needs = [
+        Need(id="F-1", text="f", children=(Child("A", "trigger"), Child("B", "act"), Child("C", "conclude")))
+    ]
+    assert flow_step_warnings(needs, _STEPS) == []
+
+
+def test_lint_command_surfaces_flow_step_warning(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    needs = """
+needs:
+  - id: F-1
+    text: a flow that never ends
+    children: [{id: US-1, step: trigger}, {id: US-2, step: act}]
+  - id: US-1
+    text: a
+  - id: US-2
+    text: b
+"""
+    code = main(["lint", "--config", str(_project(tmp_path, needs=needs))])
+    out = capsys.readouterr().out
+    assert code == 0  # a shape warning is not a hard error
+    assert "terminal step 'conclude'" in out

prodc-0.4.6/PKG-INFO

@@ -1,82 +0,0 @@
-Metadata-Version: 2.5
-Name: prodc
-Version: 0.4.6
-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
-Project-URL: Changelog, https://gitlab.com/jorgeecardona/prodc/-/blob/main/CHANGELOG.md
-Author-email: Jorge Cardona <jorgeecardona@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering
-Classifier: Topic :: Software Development :: Testing
-Classifier: Typing :: Typed
-Requires-Python: >=3.12
-Requires-Dist: pyyaml>=6
-Provides-Extra: docs
-Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
-Requires-Dist: mkdocs>=1.6; extra == 'docs'
-Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
-Description-Content-Type: text/markdown
-
-# prodc
-
-Product management as code: roles, flows, and features, each traced to the evidence behind it and the test that proves it. The aim is to make product work something a whole team can share — kept in the repo, next to the code, read by the tools you already use — rather than a specialty locked in one person's head and one tracker.
-
-prodc records that structure and checks it holds together; it does not call a model or ping a tracker. Two ideas carry it, both about not fooling yourself:
-
-1. **A need with no evidence is an opinion.** Write down who asked for something — an interview, a ticket, an email — or prodc flags it as an opinion, because that is what it is until someone outside the room has asked.
-2. **"Done" is a claim your tests back.** You attach a proof (a locator into your test suite), and `prodc status` reports each need as DELIVERED, PENDING, HOLE (an honest gap), or BROKEN. The status is read from the repo, not remembered from a standup.
-
-## Install
-
-```bash
-pip install prodc          # or: uv add prodc
-uv sync && make check      # contributors: deps + lint + typecheck + test
-```
-
-## Use
-
-```bash
-prodc status
-```
-
-```text
-prodc status — quickstart
-gaps: 2 HOLE  ·  1 opinion    coverage 1/3 (33%)
-     id        GROUNDS         need                                        WARRANT
-
-jordan (design partner)    1 DELIVERED  ·  2 HOLE
-  !! N-1       DELIVERED* 1/1   see which orders are past due at a glance   primary:Jordan
-     N-2       HOLE             export the day's delivery run sheet         secondary
-     N-3       HOLE             implement a settings page                   opinion
-       ⚠ text may be a solution in disguise (starts with 'implement')
-```
-
-GROUNDS = does a test prove it. WARRANT = did a user ask for it. The gap between them is the point.
-
-## Use it with an agent
-
-prodc ships a playbook that teaches a coding agent to run it as the project's product manager —
-read the board, capture evidence, record needs with honest provenance, find proofs, gate before a
-handoff. Drop it where your agent reads project guidance:
-
-```bash
-prodc agent >> AGENTS.md     # or: prodc agent --write AGENTS.md
-```
-
-This is how an engineer vibe-codes their way into product work: the agent does the product
-management from inside the repo, with prodc keeping it honest.
-
-## Docs
-
-- [Quickstart](docs/quickstart.md) — 60 seconds to a board
-- [Commands](docs/commands.md) — every verb, one line each
-- [Model](docs/model.md) — the nouns (Need, Role, Goal, Release) and the Need fields
-
-`docs/issues/` holds follow-ups. `AGENTS.md` is for coding agents.

prodc-0.4.6/README.md

@@ -1,56 +0,0 @@
-# prodc
-
-Product management as code: roles, flows, and features, each traced to the evidence behind it and the test that proves it. The aim is to make product work something a whole team can share — kept in the repo, next to the code, read by the tools you already use — rather than a specialty locked in one person's head and one tracker.
-
-prodc records that structure and checks it holds together; it does not call a model or ping a tracker. Two ideas carry it, both about not fooling yourself:
-
-1. **A need with no evidence is an opinion.** Write down who asked for something — an interview, a ticket, an email — or prodc flags it as an opinion, because that is what it is until someone outside the room has asked.
-2. **"Done" is a claim your tests back.** You attach a proof (a locator into your test suite), and `prodc status` reports each need as DELIVERED, PENDING, HOLE (an honest gap), or BROKEN. The status is read from the repo, not remembered from a standup.
-
-## Install
-
-```bash
-pip install prodc          # or: uv add prodc
-uv sync && make check      # contributors: deps + lint + typecheck + test
-```
-
-## Use
-
-```bash
-prodc status
-```
-
-```text
-prodc status — quickstart
-gaps: 2 HOLE  ·  1 opinion    coverage 1/3 (33%)
-     id        GROUNDS         need                                        WARRANT
-
-jordan (design partner)    1 DELIVERED  ·  2 HOLE
-  !! N-1       DELIVERED* 1/1   see which orders are past due at a glance   primary:Jordan
-     N-2       HOLE             export the day's delivery run sheet         secondary
-     N-3       HOLE             implement a settings page                   opinion
-       ⚠ text may be a solution in disguise (starts with 'implement')
-```
-
-GROUNDS = does a test prove it. WARRANT = did a user ask for it. The gap between them is the point.
-
-## Use it with an agent
-
-prodc ships a playbook that teaches a coding agent to run it as the project's product manager —
-read the board, capture evidence, record needs with honest provenance, find proofs, gate before a
-handoff. Drop it where your agent reads project guidance:
-
-```bash
-prodc agent >> AGENTS.md     # or: prodc agent --write AGENTS.md
-```
-
-This is how an engineer vibe-codes their way into product work: the agent does the product
-management from inside the repo, with prodc keeping it honest.
-
-## Docs
-
-- [Quickstart](docs/quickstart.md) — 60 seconds to a board
-- [Commands](docs/commands.md) — every verb, one line each
-- [Model](docs/model.md) — the nouns (Need, Role, Goal, Release) and the Need fields
-
-`docs/issues/` holds follow-ups. `AGENTS.md` is for coding agents.