prodc 0.4.7__tar.gz → 0.4.8__tar.gz

{prodc-0.4.7 → prodc-0.4.8}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.5
 Name: prodc
-Version: 0.4.7
+Version: 0.4.8
 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: Issues, https://gitlab.com/cardona-oss/prodc/-/issues
 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
+Keywords: evidence,product-management,requirements,testing,traceability,yaml
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -27,15 +29,42 @@ Description-Content-Type: text/markdown
 
 # prodc
 
-[![PyPI](https://img.shields.io/pypi/v/prodc)](https://pypi.org/project/prodc/)
+[![pipeline status](https://gitlab.com/cardona-oss/prodc/badges/main/pipeline.svg)](https://gitlab.com/cardona-oss/prodc/-/pipelines)
+[![PyPI version](https://img.shields.io/pypi/v/prodc.svg)](https://pypi.org/project/prodc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/prodc.svg)](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.
+Product management as code: user *needs* in YAML, each traced to the evidence a real user gave
+and the test that proves it is delivered. For teams that keep product work in the repo, next to
+the code.
 
-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:
+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.
+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.
+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, or
+   BROKEN. The state is read from the repo, not remembered from a standup.
+
+## Why prodc
+
+- **Versus Jira, Linear, other trackers.** A tracker records work items and a status someone set
+  by hand. prodc records *needs* and computes their status from the tests. No assignees, sprints,
+  comments, or notifications. Keep the tracker for the work; keep prodc for "did a real user ask
+  for this, and does a test prove it?" They connect at the edges: a source can be a ticket
+  locator (checked read-only against GitLab with `[sources.<name>] kind = "gitlab"`), a proof can
+  be any script (`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, linted in CI, and reviewed in merge requests
+  like code. "Is this done?" is answered by `prodc show N-1`.
+- **Versus plain YAML in the repo.** You could keep this structure by hand. prodc adds the schema,
+  proof resolution against real test suites, the evidence ladder, the lint, and 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 trees, parallel solution
+testing); it records needs, the evidence under them, and the decisions taken on them.
 
 ## Install
 
@@ -47,13 +76,13 @@ 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.
+Three files: where prodc looks, what people need, and a test you have probably already written.
 
 `prodc.toml`
 
 ```toml
 [prodc]
-needs = ["needs/*.yaml"]
+files = ["needs/*.yaml"]
 
 [proofs.web]
 kind = "gherkin"
@@ -117,9 +146,13 @@ jordan    1 DELIVERED   2 HOLE
        ⚠ 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.
+- **N-1 is DELIVERED** because a tagged scenario proves it (`*` = declared by tag, no test results
+  loaded yet).
+- **N-2 is a HOLE**: evidence, but no proof.
+- **N-3 is an opinion**: neither.
 
-Now close the loop from the command line. Each write command rewrites one YAML file, re-validates the whole model, and prints the diff.
+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
@@ -137,17 +170,8 @@ prodc status      # gaps: 1 PENDING · 1 HOLE   — the scenario exists, so N-2
 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.
+Rename a scenario 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.
 
 ## Key features
 
@@ -162,39 +186,37 @@ Change a scenario title without updating the need and the proof turns BROKEN; `p
 - **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
+- **Machine-checked roll-up.** `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).
+  interactive viewer), `portfolio`, and `diff` against a snapshot. The read commands take `--json`;
+  exit codes are fixed (0 ok, 1 gate failed, 2 config or load error).
+- **Coding-agent playbook.** `prodc agent >> AGENTS.md` 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. `prodc guide` is the short human onboarding guide.
 
 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)
+- **Repository:** https://gitlab.com/cardona-oss/prodc
+- **PyPI:** https://pypi.org/project/prodc/
+- **Changelog:** [CHANGELOG.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md)
+- **Documentation:** <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/))
+
+## Contributing
 
-`AGENTS.md` holds build and test instructions for coding agents working on prodc itself.
+Toolchain, CI, and the release process live in [CONTRIBUTING.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/CONTRIBUTING.md); build and test
+instructions for coding agents are in [AGENTS.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/AGENTS.md). In short: `make setup`
+then `make check` (lint + typecheck + test); `moon run :ci` is what CI runs.
 
 ## License
 
-MIT. See [LICENSE](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE).
+MIT © Jorge Cardona. See [LICENSE](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE).

{prodc-0.4.7 → prodc-0.4.8}/README.md

@@ -1,14 +1,41 @@
 # prodc
 
-[![PyPI](https://img.shields.io/pypi/v/prodc)](https://pypi.org/project/prodc/)
+[![pipeline status](https://gitlab.com/cardona-oss/prodc/badges/main/pipeline.svg)](https://gitlab.com/cardona-oss/prodc/-/pipelines)
+[![PyPI version](https://img.shields.io/pypi/v/prodc.svg)](https://pypi.org/project/prodc/)
+[![Python versions](https://img.shields.io/pypi/pyversions/prodc.svg)](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.
+Product management as code: user *needs* in YAML, each traced to the evidence a real user gave
+and the test that proves it is delivered. For teams that keep product work in the repo, next to
+the code.
 
-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:
+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.
+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.
+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, or
+   BROKEN. The state is read from the repo, not remembered from a standup.
+
+## Why prodc
+
+- **Versus Jira, Linear, other trackers.** A tracker records work items and a status someone set
+  by hand. prodc records *needs* and computes their status from the tests. No assignees, sprints,
+  comments, or notifications. Keep the tracker for the work; keep prodc for "did a real user ask
+  for this, and does a test prove it?" They connect at the edges: a source can be a ticket
+  locator (checked read-only against GitLab with `[sources.<name>] kind = "gitlab"`), a proof can
+  be any script (`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, linted in CI, and reviewed in merge requests
+  like code. "Is this done?" is answered by `prodc show N-1`.
+- **Versus plain YAML in the repo.** You could keep this structure by hand. prodc adds the schema,
+  proof resolution against real test suites, the evidence ladder, the lint, and 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 trees, parallel solution
+testing); it records needs, the evidence under them, and the decisions taken on them.
 
 ## Install
 
@@ -20,13 +47,13 @@ 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.
+Three files: where prodc looks, what people need, and a test you have probably already written.
 
 `prodc.toml`
 
 ```toml
 [prodc]
-needs = ["needs/*.yaml"]
+files = ["needs/*.yaml"]
 
 [proofs.web]
 kind = "gherkin"
@@ -90,9 +117,13 @@ jordan    1 DELIVERED   2 HOLE
        ⚠ 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.
+- **N-1 is DELIVERED** because a tagged scenario proves it (`*` = declared by tag, no test results
+  loaded yet).
+- **N-2 is a HOLE**: evidence, but no proof.
+- **N-3 is an opinion**: neither.
 
-Now close the loop from the command line. Each write command rewrites one YAML file, re-validates the whole model, and prints the diff.
+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
@@ -110,17 +141,8 @@ prodc status      # gaps: 1 PENDING · 1 HOLE   — the scenario exists, so N-2
 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.
+Rename a scenario 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.
 
 ## Key features
 
@@ -135,39 +157,37 @@ Change a scenario title without updating the need and the proof turns BROKEN; `p
 - **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
+- **Machine-checked roll-up.** `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).
+  interactive viewer), `portfolio`, and `diff` against a snapshot. The read commands take `--json`;
+  exit codes are fixed (0 ok, 1 gate failed, 2 config or load error).
+- **Coding-agent playbook.** `prodc agent >> AGENTS.md` 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. `prodc guide` is the short human onboarding guide.
 
 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)
+- **Repository:** https://gitlab.com/cardona-oss/prodc
+- **PyPI:** https://pypi.org/project/prodc/
+- **Changelog:** [CHANGELOG.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md)
+- **Documentation:** <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/))
+
+## Contributing
 
-`AGENTS.md` holds build and test instructions for coding agents working on prodc itself.
+Toolchain, CI, and the release process live in [CONTRIBUTING.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/CONTRIBUTING.md); build and test
+instructions for coding agents are in [AGENTS.md](https://gitlab.com/cardona-oss/prodc/-/blob/main/AGENTS.md). In short: `make setup`
+then `make check` (lint + typecheck + test); `moon run :ci` is what CI runs.
 
 ## License
 
-MIT. See [LICENSE](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE).
+MIT © Jorge Cardona. See [LICENSE](https://gitlab.com/cardona-oss/prodc/-/blob/main/LICENSE).

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

@@ -1,13 +1,20 @@
 [project]
 name = "prodc"
-version = "0.4.7"
+dynamic = ["version"]  # the single source of truth is __version__ in src/prodc/__init__.py (see [tool.hatch.version])
 description = "Product management as code: roles, flows, and features traced to evidence."
 readme = "README.md"
 requires-python = ">=3.12"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Jorge Cardona", email = "jorgeecardona@gmail.com" }]
-keywords = []
+keywords = [
+    "product-management",
+    "requirements",
+    "traceability",
+    "evidence",
+    "yaml",
+    "testing",
+]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -34,13 +41,25 @@ docs = [
 [project.urls]
 Homepage = "https://gitlab.com/cardona-oss/prodc"
 Repository = "https://gitlab.com/cardona-oss/prodc"
+Issues = "https://gitlab.com/cardona-oss/prodc/-/issues"
 Changelog = "https://gitlab.com/cardona-oss/prodc/-/blob/main/CHANGELOG.md"
 Documentation = "https://cardona-oss.gitlab.io/prodc/"
 
+[tool.uv]
+# After the pre-commit hook auto-bumps __version__ in the package __init__, uv must treat the
+# editable install as stale and reinstall it; without the __init__ key the next `make check`
+# runs against the old version. (pyproject is already an implicit key; __init__ is the version source.)
+cache-keys = [{ file = "pyproject.toml" }, { file = "src/prodc/__init__.py" }]
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+[tool.hatch.version]
+# The version lives as __version__ in the package itself; hatchling reads it (by regex, no import) so
+# pyproject and the runtime never disagree. scripts/bump-version rewrites that literal.
+path = "src/prodc/__init__.py"
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/prodc"]
 

prodc-0.4.8/src/prodc/__init__.py

@@ -0,0 +1,3 @@
+"""prodc: product management as code."""
+
+__version__ = "0.4.8"  # the single source of truth; pyproject reads it via [tool.hatch.version]

{prodc-0.4.7 → prodc-0.4.8}/src/prodc/agent.md

@@ -63,19 +63,23 @@ Read first, then act, then check.
 
 ## The commands you will use most
 
+`--file` takes any file matched by `[prodc].files`; every noun may live in any of them, so roles,
+principles and decisions can have their own files (say `product/decisions.yaml`) instead of
+sharing a needs file.
+
 | To… | Run |
 |---|---|
 | see the board | `prodc status [--client ID] [--json]` |
-| read one need | `prodc show <id>` |
+| read one need or decision | `prodc show <id>` |
 | rank the backlog | `prodc plan` |
 | prep a client meeting | `prodc brief <client>` |
 | record a new need (with honest provenance) | `prodc add need <id> --text "…" --who <you> --kind assumption --file needs/<f>.yaml` |
 | triage staged drafts | `prodc review` — list them; `--promote <id>…`/`--promote-all` onto the board, `--drop <id>…` to delete |
-| declare a role (the roster) | `prodc add role <id> --text "…" --file needs/<f>.yaml` |
-| declare a product principle (the vision, held as given) | `prodc add principle <id> --text "…" --file needs/<f>.yaml` — the frame that decides between clients who want opposite things; what an `out_of_scope` decision cites |
+| declare a role (the roster) | `prodc add role <id> --text "…" --file product/roles.yaml` |
+| declare a product principle (the vision, held as given) | `prodc add principle <id> --text "…" --file product/principles.yaml` — the frame that decides between clients who want opposite things; what an `out_of_scope` decision cites |
 | revise a principle (fires the re-review ripple) | `prodc revise principle <id> [--text "…"] [--date ISO]` — re-stamps `revised_at`, so every need withdrawn under it with an earlier date comes back up |
-| promote a need you commit to into a principle | `prodc add principle <id> --from-need <need-id> --file needs/<f>.yaml` — copies the need's text (unless `--text` overrides) and its sources (the client signals that surfaced it); the need stays on the board, so a need and the principle it inspired coexist |
-| record how a need gets built (the chosen solution) | `prodc add decision <id> --text "<the solution>" --needs <ids> [--alternative "<rejected>" …] [--consequences "…"] [--principles <ids>] --file needs/<f>.yaml` — the OST node: which solution you picked for a need, over what, resting on which principle. `--needs` is required (a decision with no need is refused); `lint` flags one left serving only withdrawn needs, or decided before a principle it cites was revised |
+| promote a need you commit to into a principle | `prodc add principle <id> --from-need <need-id> --file product/principles.yaml` — copies the need's text (unless `--text` overrides) and its sources (the client signals that surfaced it); the need stays on the board, so a need and the principle it inspired coexist |
+| record how a need gets built (the chosen solution) | `prodc add decision <id> --text "<the solution>" --needs <ids> [--alternative "<rejected>" …] [--consequences "…"] [--principles <ids>] --file product/decisions.yaml` — the OST node: which solution you picked for a need, over what, resting on which principle. `--needs` is required (a decision with no need is refused); `lint` flags one left serving only withdrawn needs, or decided before a principle it cites was revised |
 | attach evidence after a user said something | `prodc capture <id> --kind primary --who <person> [--role <id>] --date <ISO> --quote "…"` (`--role` records which declared role vouched for it) |
 | set or append a field | `prodc set <id> key=value` (append a list with `key+=value`, e.g. `proofs+=web:orders.feature#…`) |
 | mark two needs as opposing each other | `prodc set <id> contradicts+=<other-id>` — symmetric (declare once); `lint` flags a pair left both-live (clients want opposite things and the vision has not decided), and `withdraw … --kind out_of_scope --principle <id>` resolves it |

{prodc-0.4.7 → prodc-0.4.8}/src/prodc/cli/app.py

@@ -122,8 +122,8 @@ def main(argv: list[str] | None = None) -> int:
     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 = sub.add_parser("show", help="show one need or decision as a citable answer")
+    sh.add_argument("need_id", help="the need or decision id to show, e.g. N-1 or D-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)
@@ -546,7 +546,7 @@ def main(argv: list[str] | None = None) -> int:
         "--file",
         default=None,
         metavar="PATH",
-        help="file to write a created baseline into (must match a [prodc].needs glob)",
+        help="file to write a created baseline into (must match a [prodc].files glob)",
     )
     rc.add_argument(
         "--dry-run", action="store_true", help="with --apply: validate and show diffs, don't write"

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

@@ -88,6 +88,7 @@ from .render import (
     render_brief,
     render_columns,
     render_contradictions,
+    render_decision_show,
     render_decisions,
     render_goals,
     render_handoffs,
@@ -104,6 +105,7 @@ from .render import (
 )
 from .serialize import (
     brief_json,
+    decision_show_json,
     dup_payload,
     plan_json,
     show_json,
@@ -442,8 +444,25 @@ def cmd_show(args: argparse.Namespace) -> int:
     by_id = {r.need.id: r for r in resolve(needs, cfg.adapters, cfg.source_adapters)}
     r = by_id.get(args.need_id)
     if r is None:
-        print(f"prodc: no need '{args.need_id}'", file=sys.stderr)
-        return 2
+        decision = next((d for d in model.decisions if d.id == args.need_id), None)
+        if decision is None:
+            print(f"prodc: no need or decision '{args.need_id}'", file=sys.stderr)
+            return 2
+        # A decision is citable too (#95): the same warnings lint raises for it, shown inline.
+        warnings: list[str] = []
+        if decision in orphaned_decisions(list(model.decisions), needs):
+            warnings.append("serves only withdrawn/non-product needs — re-tie it or withdraw it")
+        warnings += [
+            f"decided {decision.decided_at} under principle {pid}, revised later — re-review"
+            for d, pid in stale_decisions(list(model.decisions), list(model.principles))
+            if d is decision
+        ]
+        print(
+            decision_show_json(decision, warnings)
+            if args.json
+            else render_decision_show(decision, needs, warnings)
+        )
+        return 0
     decisions = decisions_for(args.need_id, list(model.decisions))  # the 'how' behind this need
     print(
         show_json(r, decisions=decisions)
@@ -972,8 +991,6 @@ def cmd_capture(args: argparse.Namespace) -> int:
     return emit_edit(edit, args.dry_run, args.json)
 
 
-
-
 def _repo_row(config_path: str) -> RepoRow:
     p = Path(config_path)
     name = p.parent.name or str(p)

{prodc-0.4.7 → prodc-0.4.8}/src/prodc/cli/render.py

@@ -219,7 +219,9 @@ def render_goals(goal_cov: list[tuple[Goal, Summary]], ungoaled: list[NeedResult
         state = group_state(gsum)
         metric = f"  [{goal.metric}]" if goal.metric else ""
         pct = round(gsum.coverage * 100)
-        overdue = goal.target is not None and goal.target < today and state is not NeedState.DELIVERED
+        overdue = (
+            goal.target is not None and goal.target < today and state is not NeedState.DELIVERED
+        )
         target = ""
         if goal.target:
             target = f"  ⚠ overdue {goal.target}" if overdue else f"  target {goal.target}"
@@ -314,9 +316,7 @@ def _principle_tally(reports: list[PrincipleReport]) -> str:
         counts[rep.state] = counts.get(rep.state, 0) + 1
     parts: list[str] = []
     for scope, counts in by_scope.items():
-        inner = ", ".join(
-            f"{counts[s]} {s.value}" for s in PrincipleState if counts.get(s)
-        )
+        inner = ", ".join(f"{counts[s]} {s.value}" for s in PrincipleState if counts.get(s))
         parts.append(f"{scope}: {inner}")
     return "  ·  ".join(parts)
 
@@ -352,6 +352,35 @@ def render_decisions(decisions: list[Decision], needs: list[Need]) -> str:
     return "\n".join(out)
 
 
+def render_decision_show(d: Decision, needs: list[Need], warnings: list[str]) -> str:
+    """One decision as a citable answer (#95): the chosen solution, what it serves and rejected.
+
+    The decision counterpart of :func:`render_show` — ``prodc show D-1`` answers "how is this
+    built, over what, and why" the way ``prodc show N-1`` answers "is this delivered".
+    """
+    by_id = {n.id: n for n in needs}
+    tag = " (proposed)" if d.draft else ""
+    lines = [f"{d.id}{tag}  {d.text}"]
+    lines.append("  serves:")
+    for nid in d.needs:
+        n = by_id.get(nid)
+        lines.append(f"    - {nid}: {n.text}" if n else f"    - {nid}")
+    if d.alternatives:
+        lines.append(f"  over: {', '.join(d.alternatives)}")
+    if d.consequences:
+        lines.append(f"  consequences: {d.consequences}")
+    if d.principles:
+        lines.append(f"  rests on: {', '.join(d.principles)}")
+    if d.decided_at:
+        lines.append(f"  decided: {d.decided_at}")
+    if d.withdrawn:
+        lines.append(
+            f"  withdrawn ({d.withdrawn.kind.value}, {d.withdrawn.date}): {d.withdrawn.reason}"
+        )
+    lines += [f"  ⚠ {w}" for w in warnings]
+    return "\n".join(lines)
+
+
 def render_show(
     r: NeedResult,
     importance_label: str | None = None,
@@ -416,9 +445,7 @@ def render_show(
     else:
         lines.append("  sources: (none — opinion)")
     if need.children:
-        rendered = ", ".join(
-            c.id if c.step is None else f"{c.id}@{c.step}" for c in need.children
-        )
+        rendered = ", ".join(c.id if c.step is None else f"{c.id}@{c.step}" for c in need.children)
         lines.append(f"  children: {rendered}")
     if need.contradicts:
         lines.append(f"  contradicts: {', '.join(need.contradicts)}")

{prodc-0.4.7 → prodc-0.4.8}/src/prodc/cli/serialize.py

@@ -145,6 +145,13 @@ def to_json(
     return json.dumps(payload, indent=2)
 
 
+def decision_show_json(d: Decision, warnings: list[str]) -> str:
+    """``prodc show D-1 --json`` (#95): the decision record plus its lint-style warnings."""
+    payload = _decision_payload(d)
+    payload["warnings"] = warnings
+    return json.dumps(payload, indent=2)
+
+
 def show_json(r: NeedResult, decisions: list[Decision] | None = None) -> str:
     need = r.need
     payload = need_payload(r)  # the shared core — never drifts from the board

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

@@ -106,7 +106,9 @@ def _callbacks(raw: dict[str, object]) -> tuple[tuple[Callback, ...], str]:
 @dataclass
 class Config:
     root: Path
-    need_globs: list[str]  # the prodc files; each may carry any noun list (needs:, goals:, …)
+    # [prodc].files (+ the older alias [prodc].needs): the prodc files. Every matched file may
+    # carry any noun list (needs:, goals:, roles:, principles:, decisions:, …) — #95.
+    need_globs: list[str]
     adapters: dict[str, Adapter] = field(default_factory=dict[str, Adapter])
     source_adapters: dict[str, SourceAdapter] = field(default_factory=dict[str, SourceAdapter])
     duplicate_threshold: float = 0.8  # [lint].duplicate_threshold — dupe score to flag (#55)
@@ -131,6 +133,21 @@ class Config:
         """
         return self.flow_steps[-1] if self.flow_steps else None
 
+    def prodc_files(self) -> list[Path]:
+        """Every file matched by the configured globs, each once, in glob-then-name order.
+
+        A path matched by two globs (say ``files`` and ``needs`` overlap) is read once, so
+        its ids are not reported as duplicates of themselves.
+        """
+        seen: set[Path] = set()
+        out: list[Path] = []
+        for pattern in self.need_globs:
+            for path in sorted(self.root.glob(pattern)):
+                if path not in seen:
+                    seen.add(path)
+                    out.append(path)
+        return out
+
     def importance_label(self, level: int | None) -> str | None:
         """The declared label for an importance level, or None if unset/undeclared (#59)."""
         if level is None:
@@ -166,9 +183,14 @@ class Config:
         raw = _as_dict(tomllib.loads(path.read_text(encoding="utf-8")), "prodc.toml")
 
         prodc_tbl = _as_dict(raw.get("prodc", {}), "[prodc]")
-        need_globs = _as_str_list(prodc_tbl.get("needs", []), "[prodc].needs")
+        # `files` is the neutral name (#95); `needs` stays as an alias and the two are merged, so
+        # an existing config keeps working and a repo can split decisions/roles into their own
+        # folder without listing them under a key that says "needs".
+        files = _as_str_list(prodc_tbl.get("files", []), "[prodc].files")
+        needs = _as_str_list(prodc_tbl.get("needs", []), "[prodc].needs")
+        need_globs = files + [g for g in needs if g not in files]
         if not need_globs:
-            raise ConfigError("[prodc].needs must list at least one glob")
+            raise ConfigError("[prodc].files must list at least one glob")
 
         adapters: dict[str, Adapter] = {}
         proofs = _as_dict(raw.get("proofs", {}), "[proofs]")

{prodc-0.4.7 → prodc-0.4.8}/src/prodc/guide.md

@@ -17,7 +17,7 @@ Three files make a board.
 
 ```toml
 [prodc]
-needs = ["needs/*.yaml"]
+files = ["needs/*.yaml"]
 ```
 
 `needs/needs.yaml`:

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

@@ -529,15 +529,14 @@ def load(config: Config) -> Model:
         "principle": {},
         "decision": {},
     }
-    for pattern in config.need_globs:
-        for path in sorted(config.root.glob(pattern)):
-            f = _load_file(path, seen)
-            acc.needs.extend(f.needs)
-            acc.goals.extend(f.goals)
-            acc.releases.extend(f.releases)
-            acc.roles.extend(f.roles)
-            acc.principles.extend(f.principles)
-            acc.decisions.extend(f.decisions)
+    for path in config.prodc_files():
+        f = _load_file(path, seen)
+        acc.needs.extend(f.needs)
+        acc.goals.extend(f.goals)
+        acc.releases.extend(f.releases)
+        acc.roles.extend(f.roles)
+        acc.principles.extend(f.principles)
+        acc.decisions.extend(f.decisions)
     _check_variants(acc.needs)
     _check_children(acc.needs)
     _check_contradicts(acc.needs)
@@ -652,12 +651,16 @@ def _check_withdrawal_of(needs: list[Need]) -> None:
         if w is None:
             continue
         if w.kind is WithdrawalKind.DUPLICATE and w.of is None:
-            raise LoaderError(f"need {need.id!r}: a duplicate withdrawal must name 'of' (the original)")
+            raise LoaderError(
+                f"need {need.id!r}: a duplicate withdrawal must name 'of' (the original)"
+            )
         if w.of is not None:
             if w.of == need.id:
                 raise LoaderError(f"need {need.id!r}: withdrawn 'of' cannot be itself")
             if w.of not in known:
-                raise LoaderError(f"need {need.id!r}: withdrawn 'of' {w.of!r} is not a known need id")
+                raise LoaderError(
+                    f"need {need.id!r}: withdrawn 'of' {w.of!r} is not a known need id"
+                )
 
 
 def _check_decisions(

{prodc-0.4.7 → prodc-0.4.8}/src/prodc/writer.py

@@ -336,20 +336,9 @@ def _proof_list(need: dict[str, object], path: Path) -> list[object]:
     return list(cast("list[object]", current))
 
 
-def _config_files(config: Config) -> list[Path]:
-    seen: set[Path] = set()
-    out: list[Path] = []
-    for pattern in config.need_globs:
-        for path in sorted(config.root.glob(pattern)):
-            if path not in seen:
-                seen.add(path)
-                out.append(path)
-    return out
-
-
 def _locate(config: Config, need_id: str) -> tuple[Path, dict[str, object]]:
     """Find the file and the raw need mapping for ``need_id``."""
-    for path in _config_files(config):
+    for path in config.prodc_files():
         doc, _ = _read_doc(path)
         for raw in _need_list(doc, path):
             if isinstance(raw, dict) and cast("dict[str, object]", raw).get("id") == need_id:
@@ -411,7 +400,7 @@ def _guard_target(config: Config, path: Path) -> None:
     except ValueError:
         raise WriteError(f"{path} is outside the project root") from None
     if not any(rel.match(pattern) for pattern in config.need_globs):
-        raise WriteError(f"{path.name} does not match any [prodc].needs glob")
+        raise WriteError(f"{path.name} does not match any [prodc].files glob")
 
 
 def _validated(config: Config, path: Path, old_text: str, new_text: str, dry_run: bool) -> Edit:
@@ -496,9 +485,7 @@ def set_importance(
         need["importance"] = level
         need["importance_set_at"] = when
 
-    return _edit_one_need(
-        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
-    )
+    return _edit_one_need(config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate)
 
 
 def capture_source(
@@ -544,9 +531,7 @@ def capture_source(
         sources.append(source)
         need["sources"] = sources
 
-    return _edit_one_need(
-        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
-    )
+    return _edit_one_need(config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate)
 
 
 def attest(
@@ -632,14 +617,12 @@ def reinstate(config: Config, need_id: str, *, expect_sha: str | None, dry_run:
             raise WriteError(f"need {need_id!r} is not withdrawn")
         del need["withdrawn"]
 
-    return _edit_one_need(
-        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
-    )
+    return _edit_one_need(config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate)
 
 
 def _locate_decision(config: Config, decision_id: str) -> tuple[Path, dict[str, object], str]:
     """The file holding ``decision_id``, its parsed doc, and its raw text."""
-    for path in _config_files(config):
+    for path in config.prodc_files():
         doc, text = _read_doc(path)
         raw = doc.get("decisions")
         if not isinstance(raw, list):
@@ -745,9 +728,7 @@ def accept(
                 proofs.append(locator)
             need["proofs"] = proofs
 
-    return _edit_one_need(
-        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
-    )
+    return _edit_one_need(config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate)
 
 
 def add_proof(
@@ -759,15 +740,14 @@ def add_proof(
     batch apply can call it per need and show each need's diff. Re-adding a locator already on the
     need is a no-op, so applying the same suggestion twice does not duplicate it (#54).
     """
+
     def _mutate(need: dict[str, object], path: Path) -> None:
         proofs = _proof_list(need, path)
         if locator not in proofs:
             proofs.append(locator)
         need["proofs"] = proofs
 
-    return _edit_one_need(
-        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
-    )
+    return _edit_one_need(config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate)
 
 
 def relink_proof(
@@ -787,6 +767,7 @@ def relink_proof(
     old locator is not actually on the need. One reload-gated single-file splice, like
     :func:`add_proof`.
     """
+
     def _mutate(need: dict[str, object], path: Path) -> None:
         proofs = _proof_list(need, path)
         if old_locator not in proofs:
@@ -798,9 +779,7 @@ def relink_proof(
                 deduped.append(p)
         need["proofs"] = deduped
 
-    return _edit_one_need(
-        config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate
-    )
+    return _edit_one_need(config, need_id, expect_sha=expect_sha, dry_run=dry_run, mutate=_mutate)
 
 
 def add_need(
@@ -963,7 +942,7 @@ def add_principle(
 
 def _locate_principle(config: Config, principle_id: str) -> tuple[Path, dict[str, object], str]:
     """The file holding ``principle_id``, its parsed doc, and its raw text."""
-    for path in _config_files(config):
+    for path in config.prodc_files():
         doc, text = _read_doc(path)
         raw = doc.get("principles")
         if not isinstance(raw, list):
@@ -1110,7 +1089,7 @@ def link_variant_group(
     snapshotted up front; any rejection — or ``dry_run`` — restores every one, so the group is
     linked all-or-nothing.
     """
-    touched = _config_files(config)
+    touched = config.prodc_files()
     if create_baseline:
         if not baseline_file or baseline_text is None:
             raise WriteError("creating a baseline needs both a file and text")

prodc-0.4.8/tests/test_files_key.py

@@ -0,0 +1,103 @@
+"""`[prodc].files` (#95): one neutral key for the prodc files, `needs` kept as an alias, and
+`prodc show` answering for a decision as well as a need."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from prodc.config import Config, ConfigError
+from prodc.loader import load
+
+_NEEDS = "needs:\n  - id: N-1\n    text: see past-due orders\n"
+_DECISIONS = """decisions:
+  - id: D-1
+    text: highlight rows in red
+    needs: [N-1]
+    alternatives: [a separate past-due tab]
+    consequences: colour carries meaning
+"""
+
+
+def _project(tmp_path: Path, prodc_tbl: str) -> Path:
+    (tmp_path / "product" / "needs").mkdir(parents=True)
+    (tmp_path / "product" / "decisions").mkdir(parents=True)
+    (tmp_path / "product" / "needs" / "a.yaml").write_text(_NEEDS, encoding="utf-8")
+    (tmp_path / "product" / "decisions" / "d.yaml").write_text(_DECISIONS, encoding="utf-8")
+    (tmp_path / "prodc.toml").write_text(f"[prodc]\n{prodc_tbl}\n", encoding="utf-8")
+    return tmp_path / "prodc.toml"
+
+
+def test_files_key_reads_every_noun_from_its_own_folder(tmp_path: Path) -> None:
+    cfg = Config.load(
+        _project(tmp_path, 'files = ["product/needs/*.yaml", "product/decisions/*.yaml"]')
+    )
+    model = load(cfg)
+    assert [n.id for n in model.needs] == ["N-1"]
+    assert [d.id for d in model.decisions] == ["D-1"]
+
+
+def test_needs_key_still_works_as_alias(tmp_path: Path) -> None:
+    cfg = Config.load(
+        _project(tmp_path, 'needs = ["product/needs/*.yaml", "product/decisions/*.yaml"]')
+    )
+    assert [d.id for d in load(cfg).decisions] == ["D-1"]
+
+
+def test_files_and_needs_merge_and_overlap_is_read_once(tmp_path: Path) -> None:
+    # product/needs/*.yaml is matched by both keys: it must load once, not as a duplicate id.
+    toml = 'files = ["product/**/*.yaml"]\nneeds = ["product/needs/*.yaml"]'
+    cfg = Config.load(_project(tmp_path, toml))
+    assert cfg.need_globs == ["product/**/*.yaml", "product/needs/*.yaml"]
+    model = load(cfg)
+    assert [n.id for n in model.needs] == ["N-1"]
+    assert [d.id for d in model.decisions] == ["D-1"]
+
+
+def test_no_glob_is_a_config_error_naming_files(tmp_path: Path) -> None:
+    with pytest.raises(ConfigError, match=r"\[prodc\]\.files must list at least one glob"):
+        Config.load(_project(tmp_path, ""))
+
+
+def test_write_outside_globs_names_files_key(tmp_path: Path) -> None:
+    from prodc.writer import WriteError, add_principle
+
+    cfg = Config.load(_project(tmp_path, 'files = ["product/needs/*.yaml"]'))
+    with pytest.raises(WriteError, match=r"\[prodc\]\.files glob"):
+        add_principle(
+            cfg, "P-1", "local-first", file="elsewhere/p.yaml", revised_at="2026-10-20", dry_run=True
+        )
+
+
+def test_show_prints_a_decision(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    cfg = _project(tmp_path, 'files = ["product/**/*.yaml"]')
+    assert main(["show", "D-1", "--config", str(cfg)]) == 0
+    out = capsys.readouterr().out
+    assert "D-1  highlight rows in red" in out
+    assert "N-1: see past-due orders" in out  # what it serves, with the need's text
+    assert "over: a separate past-due tab" in out
+    assert "consequences: colour carries meaning" in out
+
+
+def test_show_decision_json(tmp_path: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from prodc.cli import main
+
+    cfg = _project(tmp_path, 'files = ["product/**/*.yaml"]')
+    assert main(["show", "D-1", "--json", "--config", str(cfg)]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["id"] == "D-1" and payload["needs"] == ["N-1"]
+    assert payload["warnings"] == []
+
+
+def test_show_unknown_id_names_both_kinds(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    from prodc.cli import main
+
+    cfg = _project(tmp_path, 'files = ["product/**/*.yaml"]')
+    assert main(["show", "X-9", "--config", str(cfg)]) == 2
+    assert "no need or decision 'X-9'" in capsys.readouterr().err

prodc-0.4.7/src/prodc/__init__.py

@@ -1,8 +0,0 @@
-"""prodc: product management as code."""
-
-from importlib.metadata import PackageNotFoundError, version
-
-try:
-    __version__ = version("prodc")
-except PackageNotFoundError:  # running from source without installed metadata
-    __version__ = "0+unknown"