Document rules and enforce price value uniqueness

modules/purchase_trade/docs/documentation-management.md

@@ -0,0 +1,82 @@
+# Documentation Management - Purchase Trade
+
+This guide records the documentation workflow to apply for future `purchase_trade` developments.
+
+## Rule Documentation Structure
+
+- Keep `business-rules.md` as the entry point and rule catalog.
+- Store detailed business rules in `docs/rules/`, one file per substantial rule.
+- Use stable business rule IDs such as `BR-PT-004`.
+- Add every new detailed rule to the catalog in `business-rules.md`.
+- Keep rule files focused on business behavior, expected outcomes, edge cases, impacted files, tests, and open questions.
+
+## Rule File Template
+
+Use this structure for detailed rule files when applicable:
+
+- Intent
+- Scope
+- Inputs
+- Date and Numeric Parsing, when relevant
+- Expected Behavior
+- Defaults or Derived Values, when relevant
+- Result Reporting, when relevant
+- Edge Cases
+- Impacted Files
+- Tests
+- Open Questions
+
+## Open Questions
+
+- In `Open Questions`, prefix every question with `Q:`.
+- Prefix every documented answer with `A:`.
+- When an answer differs from current code behavior, add a short `Comment:` explaining that a code change is required.
+- Once all questions have answers, keep the section as decision history unless the rule becomes noisy.
+
+Example:
+
+```md
+- Q: Should missing `price_value` be allowed?
+- A: Missing `price_value` is not allowed. Report the row as an error.
+- Comment: current code allows empty `price_value`. Implementing this answer requires a code change.
+```
+
+## Backlog From Documentation
+
+- When answered questions imply code changes, create a dedicated backlog file for the feature or rule.
+- Store all backlog files in `docs/backlog/`.
+- Name backlog files by feature, for example `docs/backlog/market-price-import-backlog.md`.
+- Do not use a generic module backlog when the changes belong to one feature.
+- After coding a backlog item, update that item with the work done and mark its `Status` as `to be tested` until the targeted validation has run successfully in the proper environment.
+- After committing implemented backlog work, record the implementation commit hash in the relevant backlog item for future reference.
+- Each backlog item should include:
+  - stable ID
+  - status
+  - implementation commit, once committed
+  - priority
+  - source rule file
+  - requirement
+  - work done, once implemented
+  - validation status, once attempted
+  - current behavior, when useful
+  - expected code impact
+  - expected tests
+
+## Review Workflow
+
+For future development work:
+
+1. Read the relevant rule file before changing code.
+2. Review the current code and tests related to the rule.
+3. Update the rule documentation if code review reveals missing behavior, edge cases, defaults, or test gaps.
+4. Record unresolved decisions as `Q:` entries.
+5. Record accepted decisions as `A:` entries.
+6. Convert accepted decisions that require code changes into backlog items.
+7. Implement code only after the requested documentation/specification step is complete, or after explicit approval when the user asks to wait.
+
+## Scope Discipline
+
+- Keep documentation changes close to the affected module and feature.
+- Do not mix unrelated features in one rule file or one backlog file.
+- Link or list impacted files so future agents can work in a narrow code scope.
+- Keep tests listed near the rule they validate.