feat(mvrs): add MVR supersession, latest dated MVR per SVC determines verdict (#399)

* feat(mvrs): supersession — latest MVR per SVC wins (#72)

When an SVC is manually verified more than once (e.g. a first MVR
fails, a fix is applied, and a second MVR passes), the requirement
was incorrectly reported as not met because all MVRs were counted.

Supersession rule: the MVR with the latest date is the verdict for
that SVC; older ones are retained as audit history but excluded from
the pass/fail computation.

Changes:
- Add optional `date` field (RFC 3339 date-time with timezone) to
  mvrs.yml schema; `date` is required when >1 MVR references the
  same SVC.
- `MVRData.date: Optional[datetime]` — timezone-aware; stored as
  original ISO string in SQLite, sorted via SQLite's `datetime()`
  function so mixed offsets compare correctly by UTC moment.
- `RequirementsRepository.get_effective_mvr_for_svc()` — new SQL
  query using `ORDER BY datetime(date) DESC NULLS LAST LIMIT 1`.
- `RequirementsRepository.get_superseded_mvrs_for_svc()` — all
  non-effective MVRs for a SVC (audit history).
- `StatisticsService` — verdict computed from effective MVR per SVC;
  removes the now-redundant `_get_mvr_stats` helper.
- `details.py` — `_compute_meets` uses effective MVR; `get_svc_details`
  adds `date` and `superseded` fields to each MVR.
- `SemanticValidator._validate_mvr_supersession` — errors on missing
  `date` when multiple MVRs reference the same SVC, and on exact UTC
  timestamp ties.
- Report templates (AsciiDoc + Markdown) — show `date` and mark
  superseded MVRs as history.
- Export service + schema — include `date` field.

Closes #72

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

* fix(mvrs): address PR review findings

- export_service: serialize MVRData.date as ISO string (.isoformat()) to
  prevent TypeError on JSON export
- details.py: serialize date in get_svc_details and get_mvr_details the
  same way; both previously passed raw datetime objects to callers
- report.py: same fix for the Jinja2 template dict (renders T not space)
- schema.py: add idx_mvrs_date index to support ORDER BY datetime(date)
- requirements_repository: replace cascading-N+1 in
  get_superseded_mvrs_for_svc with a single ROW_NUMBER window query;
  add get_effective_mvr_verdict_counts() batch aggregation method;
  document the datetime() TZ-normalization in get_effective_mvr_for_svc
- statistics_service: replace per-SVC loop in _calculate_global_totals
  with single get_effective_mvr_verdict_counts() call (eliminates N+1)
- tests: add _validate_mvr_supersession unit tests (missing date,
  tie-break, valid pair, single undated); add supersession scenarios to
  test_details (compute_meets, get_svc_details superseded flag,
  get_mvr_details date field); add 3-MVR and global-totals tests to
  test_statistics_service; add date serialization round-trip tests to
  test_export_service

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

* docs: document MVR supersession and date field

- usage.adoc: update Manual Tests column description to mention
  supersession; add new [[mvr-supersession]] section with YAML example,
  date field rules (required when >1 MVR per SVC, RFC 3339 format,
  tie-break is a validation error, quotes required in YAML)
- how_it_works.adoc: add MVR verdict and supersession section explaining
  the single-query effective-MVR selection and global totals semantics

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

* docs: use RFC 3339 instead of ISO 8601 for MVR date field

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

* docs: update mcp.adoc and lsp.adoc for MVR date and superseded fields

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

---------

Signed-off-by: Jimisola Laursen <jimisola@jimisola.com>

Author: jimisola

docs/modules/ROOT/pages/how_it_works.adoc

@@ -36,6 +36,16 @@ For each implementation node, `requirements.yml` is parsed (validation runs) but
 
 NOTE: `imports:` sections of implementation nodes are not followed — an implementation's own imports belong to a different scope.
 
+== MVR verdict and supersession
+
+`StatisticsService` computes the manual-test verdict for each SVC by calling `RequirementsRepository.get_effective_mvr_for_svc()`.
+When a SVC has multiple MVRs, the one with the *latest `date`* (UTC-normalised via SQLite's `datetime()` function so mixed timezone offsets compare correctly) is the verdict; all others are superseded.
+When a SVC has only one MVR — dated or undated — that entry is always the verdict.
+
+The global totals (`total_manual_tests`, `passed_manual_tests`, `failed_manual_tests`) are computed in a single SQL aggregation query and count one effective verdict per SVC, never superseded entries.
+
+See xref:usage.adoc#mvr-supersession[MVR supersession] for the YAML format rules and examples.
+
 == The `variant` field
 
 `variant: system/microservice/external` in `requirements.yml` is optional advisory metadata. It is not a behavioral gate — parsing is entirely presence-based. If a file exists, it is read. If a section exists in YAML, it is parsed.

docs/modules/ROOT/pages/lsp.adoc

@@ -246,11 +246,11 @@ The full protocol spec (OpenRPC) is at `docs/modules/ROOT/lsp/reqstool-lsp.openr
 
 | `svc`
 | `SVC_001`
-| Full SVC with linked requirements, test annotations, test results, and MVRs
+| Full SVC with linked requirements, test annotations, test results, and MVRs (each with `date` and `superseded` flag)
 
 | `mvr`
 | `MVR_001`
-| Manual verification result with linked SVC IDs
+| Manual verification result with linked SVC IDs, RFC 3339 date, and `superseded` flag
 
 | `urn`
 | `my-service`

docs/modules/ROOT/pages/mcp.adoc

@@ -131,6 +131,9 @@ Full details for a single SVC.
 
 *Returns:* `{ type, id, urn, title, description, verification, instructions, revision, lifecycle, requirement_ids, test_annotations, test_results, test_summary, mvrs, location, source_paths }`
 
+Each entry in `mvrs` is `{ id, urn, passed, date, comment, superseded }`.
+`date` is an RFC 3339 date-time string or empty string; `superseded: true` means an older entry that was superseded by a later one.
+
 ==== `get_mvr`
 
 Full details for a single MVR.
@@ -139,7 +142,9 @@ Full details for a single MVR.
 
 * `id` _(string, required)_
 
-*Returns:* `{ type, id, urn, passed, comment, svc_ids, location, source_paths }`
+*Returns:* `{ type, id, urn, passed, date, comment, svc_ids, location, source_paths }`
+
+`date` is an RFC 3339 date-time string, or an empty string if the MVR has no date.
 
 ==== `get_urn_details`
 

docs/modules/ROOT/pages/usage.adoc

@@ -108,7 +108,8 @@ The requirements table shows for each requirement:
 ** `framework` -- `framework`: fulfilled by framework auto-configuration (Spring Boot starters, OTel agents); no annotation required
 ** `N/A` -- not applicable, intentionally deferred, or out of scope; no annotation required
 * *Automated Tests* -- test results from JUnit XML: T=total SVCs, P=passed, F=failed, S=skipped, M=missing (no test found for SVC)
-* *Manual Tests* -- manual verification results: T=total, P=passed, F=failed, M=missing
+* *Manual Tests* -- manual verification results: T=total, P=passed, F=failed, M=missing.
+When multiple MVRs exist for the same SVC, only the one with the latest `date` counts (supersession); older ones are retained as audit history in the report but excluded from the verdict.
 
 The summary panels below the table break down requirements by implementation type.
 The `In Code` panel shows total, verified, annotated-not-verified, and missing-annotation counts (all percentages relative to in-code requirements).
@@ -120,6 +121,38 @@ The `N/A`, `Configuration`, `Platform`, and `Framework` panels each show three c
 
 The exit code equals the number of unmet requirements, making it suitable for CI/CD gates (`exit 0` = all requirements met).
 
+[[mvr-supersession]]
+=== MVR supersession
+
+When a manual verification is repeated (for example, a first attempt fails and a corrected one passes), add both results as separate MVR entries and set a `date` on each.
+Reqstool selects the entry with the *latest date* as the effective verdict for that SVC.
+Older entries are retained as audit history and shown with a `(superseded)` marker in the report, but are excluded from the pass/fail computation.
+
+[source,yaml]
+----
+results:
+  - id: MVR_001
+    svc_ids: ["SVC_021"]
+    date: "2026-01-10T09:00:00Z"   # <1>
+    pass: false
+    comment: "XSD validation failed."
+
+  - id: MVR_002
+    svc_ids: ["SVC_021"]
+    date: "2026-01-15T14:30:00Z"   # <2>
+    pass: true
+    comment: "All fields present."
+----
+<1> Older entry — superseded, shown as history in the report.
+<2> Latest entry — effective verdict; this determines pass/fail.
+
+*`date` field rules:*
+
+* The `date` value must be an *RFC 3339 date-time*, for example `"2026-01-15T14:30:00Z"` or `"2026-01-15T14:30:00+01:00"`. A timezone offset is mandatory — bare local datetimes without a timezone are rejected. Note the required quotes — unquoted values are parsed by YAML as `date` objects, not strings.
+* `date` is *optional* when only one MVR references a given SVC; the single entry is always the verdict regardless.
+* `date` is *required* on every MVR that references a given SVC as soon as more than one MVR does. A missing `date` in that situation is a semantic validation error.
+* Two MVRs for the same SVC with the *exact same UTC moment* are a validation error — add a time component to disambiguate (e.g. `T09:00:00Z` vs `T14:30:00Z`).
+
 [[report]]
 == Command: report
 

src/reqstool/commands/report/report.py

@@ -14,7 +14,6 @@
 from reqstool.common.validators.semantic_validator import SemanticValidator
 from reqstool.locations.location import LocationInterface
 from reqstool.models.annotations import AnnotationData
-from reqstool.models.mvrs import MVRData
 from reqstool.models.svcs import SVCData
 from reqstool.models.test_data import TEST_RUN_STATUS
 from reqstool.services.statistics_service import StatisticsService
@@ -161,11 +160,21 @@ def __aggregated_requirements_data(
             # get all implementations for current requirement
             impls: list = self._get_annotation_impls(repo=repo, urn_id=urn_id)
 
-            # Get MVR IDs via SVCs
+            # Get MVR IDs via SVCs, annotated with supersession state
             mvr_ids: list[UrnId] = [mid for svc_uid in svcs_urn_ids for mid in repo.get_mvrs_for_svc(svc_uid)]
-
-            # Get mvrs for current requirement if there are any (else [])
-            mvrs: list[MVRData] = [all_mvrs[mvr_id] for mvr_id in mvr_ids if mvr_id in all_mvrs] if mvr_ids else []
+            superseded_ids = {m.id for svc_uid in svcs_urn_ids for m in repo.get_superseded_mvrs_for_svc(svc_uid)}
+            mvrs = [
+                {
+                    "id": all_mvrs[mid].id,
+                    "passed": all_mvrs[mid].passed,
+                    "date": all_mvrs[mid].date.isoformat() if all_mvrs[mid].date is not None else "",
+                    "comment": all_mvrs[mid].comment,
+                    "svc_ids": all_mvrs[mid].svc_ids,
+                    "superseded": mid in superseded_ids,
+                }
+                for mid in mvr_ids
+                if mid in all_mvrs
+            ]
 
             # generate templates for tests related to current requirement
             automated_test_results_for_req: list = self._get_annotated_automated_test_results_for_req(

src/reqstool/commands/report/templates/asciidoc/mvrs.j2

@@ -5,7 +5,11 @@
 [cols="1a,1"]
 |===
 |*MVR ID*|*Result*
-|{{mvr_info.id.urn}}:{{mvr_info.id.id}}| {%if mvr_info.passed%} passed {% else %} failed {%endif%}
+|{{mvr_info.id.urn}}:{{mvr_info.id.id}}{% if mvr_info.superseded %} _(superseded)_{%endif%}| {%if mvr_info.passed%} passed {% else %} failed {%endif%}
+{%if mvr_info.date%}
+2+|*Date*
+2+|{{mvr_info.date}}
+{%endif%}
 2+|*Comment*
 2+|{{mvr_info.comment}}
 2+|*Referenced SVCs*

src/reqstool/commands/report/templates/markdown/mvrs.j2

@@ -5,7 +5,11 @@
 | | |
 |---|---|
 | **MVR ID** | **Result** |
-| {{mvr_info.id.urn}}:{{mvr_info.id.id}} | {%if mvr_info.passed%}passed{% else %}failed{%endif%} |
+| {{mvr_info.id.urn}}:{{mvr_info.id.id}}{% if mvr_info.superseded %} *(superseded)*{%endif%} | {%if mvr_info.passed%}passed{% else %}failed{%endif%} |
+{%if mvr_info.date%}
+| **Date** | |
+| {{mvr_info.date}} | |
+{%endif%}
 | **Comment** | |
 | {{mvr_info.comment}} | |
 | **Referenced SVCs** | |

src/reqstool/common/queries/details.py

@@ -24,13 +24,11 @@ def _compute_meets(req, repo: RequirementsRepository, svc_urn_ids: list, all_pas
             return False
     else:
         raise ValueError(f"Unhandled IMPLEMENTATION value: {req.implementation}")
-    # Check MVR results — automated test_summary misses manual verification outcomes
-    all_mvrs = repo.get_all_mvrs()
+    # Check MVR results using only the effective (latest) verdict per SVC
     for svc_uid in svc_urn_ids:
-        for mvr_id in repo.get_mvrs_for_svc(svc_uid):
-            mvr = all_mvrs.get(mvr_id)
-            if mvr is not None and not mvr.passed:
-                return False
+        effective = repo.get_effective_mvr_for_svc(svc_uid)
+        if effective is not None and not effective.passed:
+            return False
     return True
 
 
@@ -109,9 +107,10 @@ def get_svc_details(
     if svc is None:
         return None
 
-    mvr_urn_ids = repo.get_mvrs_for_svc(svc.id)
     all_mvrs = repo.get_all_mvrs()
+    mvr_urn_ids = repo.get_mvrs_for_svc(svc.id)
     mvrs = [all_mvrs[uid] for uid in mvr_urn_ids if uid in all_mvrs]
+    superseded_ids = {m.id for m in repo.get_superseded_mvrs_for_svc(svc.id)}
 
     test_annotations = repo.get_annotations_tests_for_svc(svc.id)
     test_results = repo.get_test_results_for_svc(svc.id)
@@ -154,7 +153,9 @@ def get_svc_details(
                 "id": m.id.id,
                 "urn": m.id.urn,
                 "passed": m.passed,
+                "date": m.date.isoformat() if m.date is not None else "",
                 "comment": m.comment or "",
+                "superseded": m.id in superseded_ids,
             }
             for m in mvrs
         ],
@@ -181,6 +182,7 @@ def get_mvr_details(
         "id": mvr.id.id,
         "urn": mvr.id.urn,
         "passed": mvr.passed,
+        "date": mvr.date.isoformat() if mvr.date is not None else "",
         "comment": mvr.comment or "",
         "svc_ids": [{"id": s.id, "urn": s.urn} for s in mvr.svc_ids],
         "location": repo.get_urn_location(mvr.id.urn),

src/reqstool/common/validators/semantic_validator.py

@@ -13,6 +13,7 @@
 from reqstool.common.utils import Utils
 from reqstool.common.validator_error_holder import ValidationError, ValidationErrorHolder
 from reqstool.models.imports import ImportDataInterface
+from reqstool.models.mvrs import MVRData
 from reqstool.models.raw_datasets import CombinedRawDataset
 from reqstool.models.requirements import RequirementData
 from reqstool.models.svcs import SVCData, SVCsData
@@ -47,6 +48,9 @@ def validate_post_parsing(self, combined_raw_dataset: CombinedRawDataset) -> Lis
         self._validation_error_holder.add_errors(
             self._validate_mvr_refers_to_existing_svc_ids(combined_raw_dataset=combined_raw_dataset)
         )
+        self._validation_error_holder.add_errors(
+            self._validate_mvr_supersession(combined_raw_dataset=combined_raw_dataset)
+        )
 
         errors = self._validation_error_holder.get_errors()
 
@@ -215,6 +219,60 @@ def _validate_mvr_refers_to_existing_svc_ids(
 
         return errors
 
+    def _validate_mvr_supersession(self, combined_raw_dataset: CombinedRawDataset) -> List[ValidationError]:
+        """Validate supersession rules when multiple MVRs reference the same SVC.
+
+        Rules:
+        - If >1 MVR references the same SVC, every such MVR must have a ``date`` field.
+        - No two MVRs for the same SVC may represent the exact same UTC moment (tie-break
+          is an error — use a different timestamp to disambiguate).
+        """
+        errors: List[ValidationError] = []
+        for model, model_data in combined_raw_dataset.raw_datasets.items():
+            if model != combined_raw_dataset.initial_model_urn or not model_data.mvrs_data:
+                continue
+
+            svc_to_mvrs: dict[UrnId, List[MVRData]] = {}
+            for mvr_data in model_data.mvrs_data.results.values():
+                for svc_id in mvr_data.svc_ids:
+                    svc_to_mvrs.setdefault(svc_id, []).append(mvr_data)
+
+            for svc_id, mvrs in svc_to_mvrs.items():
+                if len(mvrs) > 1:
+                    errors.extend(self._check_mvr_dates_for_svc(svc_id, mvrs))
+
+        return errors
+
+    def _check_mvr_dates_for_svc(self, svc_id: UrnId, mvrs: List[MVRData]) -> List[ValidationError]:
+        errors: List[ValidationError] = []
+        dated: list[tuple] = []
+        for mvr in mvrs:
+            if mvr.date is None:
+                errors.append(
+                    ValidationError(
+                        msg=f"MVR '{self.prettify_urn_id(mvr.id)}' references SVC "
+                        f"'{self.prettify_urn_id(svc_id)}' but has no 'date' field. "
+                        f"A 'date' is required when multiple MVRs reference the same SVC."
+                    )
+                )
+            else:
+                dated.append((mvr.date, mvr))
+
+        seen: dict = {}
+        for ts, mvr in dated:
+            if ts in seen:
+                errors.append(
+                    ValidationError(
+                        msg=f"MVRs '{self.prettify_urn_id(seen[ts].id)}' and "
+                        f"'{self.prettify_urn_id(mvr.id)}' both reference SVC "
+                        f"'{self.prettify_urn_id(svc_id)}' at the same UTC moment. "
+                        f"Use a different timestamp to disambiguate."
+                    )
+                )
+            else:
+                seen[ts] = mvr
+        return errors
+
     def _validate_svc_imports_filter_has_excludes_xor_includes(self, svc_data: SVCsData) -> List[ValidationError]:
         if "filters" in svc_data:
             for urn in svc_data["filters"].keys():

src/reqstool/model_generators/mvrs_model_generator.py

@@ -75,6 +75,7 @@ def __parse_mvrs(
                 svc_ids=Utils.convert_ids_to_urn_id(ids=result.svc_ids, urn=self.urn),
                 comment=result.comment,
                 passed=result.pass_,
+                date=result.date,
                 source_line=source_lines[result.id][0] if result.id in source_lines else None,
                 source_col_start=source_lines[result.id][1] if result.id in source_lines else None,
                 source_col_end=source_lines[result.id][2] if result.id in source_lines else None,