okstra 0.144.0 → 0.145.0

package/runtime/validators/validate-report-views.py

@@ -3,7 +3,8 @@
 (``scripts/okstra-render-report-views.py``).
 
 Checks, for a given final-report MD path:
-  1. ``*.html`` sibling exists.
+  1. ``*.html`` sibling exists when the report has clarification rows,
+     an analysis-review contract, or a plan-approval contract.
   2. HTML's ``source-sha256`` in run-meta matches the current MD body —
      stale html detection.
   3. HTML's §5.6 / §5.7 / §5.8 deliverable regions contain no
@@ -13,6 +14,8 @@ Checks, for a given final-report MD path:
      ``<img src=>`` — self-contained guarantee.
   5. Every Response ID in HTML matches the §1 Clarification Items table
      of the source MD (1:1).
+  6. Analysis reports contain all three Analysis Review decisions and an
+     affected-ID selector exactly matching the structured IDs in data.json.
 
 Exit codes: 0 on success, 1 on any failure. Failures are printed one
 per line to stderr.
@@ -34,6 +37,7 @@ from okstra_ctl.clarification_items import (  # noqa: E402
     section_1_present_but_unparsed,
 )
 from okstra_ctl.report_views import (  # noqa: E402
+    analysis_review_context,
     extract_html_digest,
     plan_approval_context,
     source_digest,
@@ -47,6 +51,18 @@ _EXTERNAL_URL_RE = re.compile(
 )
 
 _RESPONSE_ID_ATTR_RE = re.compile(r'data-response-id="(C-\d+)"')
+_ANALYSIS_REVIEW_SECTION_RE = re.compile(
+    r'<section id="analysis-review">(?P<body>.*?)</section>', re.DOTALL
+)
+_ANALYSIS_REVIEW_STATUS_RE = re.compile(
+    r'name="analysis-review-status"\s+value="([^"]+)"'
+)
+_ANALYSIS_REVIEW_SELECTOR_RE = re.compile(
+    r'<select id="analysis-review-affected-ids"[^>]*>(?P<body>.*?)</select>',
+    re.DOTALL,
+)
+_OPTION_VALUE_RE = re.compile(r'<option value="([^"]+)">')
+_ANALYSIS_REVIEW_STATUSES = ["accepted", "rejected", "revision-requested"]
 
 
 def _main_body(html_text: str) -> str:
@@ -78,6 +94,34 @@ def _no_form_sections(html_body: str) -> list[str]:
     return chunks
 
 
+def _validate_analysis_review_html(
+    html_text: str, expected_ids: tuple[str, ...]
+) -> list[str]:
+    section = _ANALYSIS_REVIEW_SECTION_RE.search(html_text)
+    if section is None:
+        return ["analysis report html is missing the Analysis Review control"]
+    body = section.group("body")
+    failures: list[str] = []
+    statuses = sorted(_ANALYSIS_REVIEW_STATUS_RE.findall(body))
+    if statuses != _ANALYSIS_REVIEW_STATUSES:
+        failures.append(
+            "Analysis Review controls must be exactly accepted, "
+            "revision-requested, and rejected"
+        )
+    selector = _ANALYSIS_REVIEW_SELECTOR_RE.search(body)
+    actual_ids = (
+        sorted(_OPTION_VALUE_RE.findall(selector.group("body")))
+        if selector is not None
+        else []
+    )
+    if actual_ids != sorted(expected_ids):
+        failures.append(
+            f"Analysis Review selector mismatch: data.json has "
+            f"{sorted(expected_ids)}, HTML has {actual_ids}"
+        )
+    return failures
+
+
 def validate(report_path: Path) -> list[str]:
     failures: list[str] = []
     if not report_path.is_file():
@@ -94,14 +138,16 @@ def validate(report_path: Path) -> list[str]:
             "form parity. Re-render the report so §1 matches the schema."
         ]
     md_ids = _md_response_ids(md)
+    review_ctx = analysis_review_context(report_path)
 
-    # (1) sibling artifact exists — conditional on §1 clarification rows.
-    # The html view's sole value over the MD is its embedded form widgets
-    # for §1 C-* rows, so a clarification-free report intentionally has no
-    # html sibling (see report_views.report_has_clarification_items). When
-    # there are no C-* rows and no html, that is the expected skip state.
+    # (1) sibling artifact exists when clarification rows or a structured
+    # analysis-review / plan-approval contract require interactive controls.
     if not html_path.is_file():
-        if not md_ids and plan_approval_context(report_path, md) is None:
+        if (
+            not md_ids
+            and plan_approval_context(report_path, md) is None
+            and review_ctx is None
+        ):
             return []
         return [f"missing html artifact: {html_path}"]
 
@@ -146,6 +192,14 @@ def validate(report_path: Path) -> list[str]:
             f"Response ID mismatch: MD §1 has {md_ids}, HTML has {html_ids}"
         )
 
+    review_section_present = _ANALYSIS_REVIEW_SECTION_RE.search(html_text) is not None
+    if review_ctx is not None:
+        failures.extend(
+            _validate_analysis_review_html(html_text, review_ctx.selector_ids)
+        )
+    elif review_section_present:
+        failures.append("non-analysis report html must not contain Analysis Review controls")
+
     return failures
 
 

package/runtime/validators/validate-run.py

@@ -21,6 +21,8 @@ from typing import Any
 # copy under ~/.okstra/lib. The manifests advertise the bare script path, so
 # it must self-bootstrap rather than rely on an inherited PYTHONPATH.
 _VALIDATORS_DIR = Path(__file__).resolve().parent
+if str(_VALIDATORS_DIR) not in sys.path:
+    sys.path.insert(0, str(_VALIDATORS_DIR))
 for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
     if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
         sys.path.insert(0, str(_ssot_dir))
@@ -96,6 +98,7 @@ from okstra_ctl.worker_prompt_contract import (  # noqa: E402
     PromptRecord,
     validate_initial_prompt_records,
 )
+from validate_analysis_report import validate_analysis_report  # noqa: E402
 from okstra_ctl.convergence_engine import (  # noqa: E402
     grouped_input_digest,
     validate_final_state,
@@ -2988,6 +2991,9 @@ def validate_final_report_data(
     failures: list[str],
     *,
     report_contracts: set[str] | None = None,
+    run_manifest: dict | None = None,
+    project_root: Path | None = None,
+    clarification_text: str = "",
 ) -> Mapping[str, Any] | None:
     """Validate the final-report data.json against the v1.0 schema.
 
@@ -3036,6 +3042,21 @@ def validate_final_report_data(
     errors = schema_validate(data, schema)
     for err in errors:
         failures.append(f"final-report data.json: {err}")
+    if errors:
+        return data
+
+    analysis_result = validate_analysis_report(
+        data=data,
+        report_path=report_path,
+        project_root=project_root or report_path.parent,
+        run_manifest=run_manifest or {},
+        clarification_text=clarification_text,
+    )
+    manifest_task_type = str((run_manifest or {}).get("taskType") or "")
+    task_type = manifest_task_type or str(
+        (data.get("header") or {}).get("taskType") or ""
+    )
+    failures.extend(f"{task_type}: {error}" for error in analysis_result.errors)
 
     _validate_rationale_evidence(data, failures)
     _validate_no_opaque_id_references(data, failures)
@@ -4117,6 +4138,22 @@ def _carry_in_source_for_run(run_manifest_path: Path) -> str:
     return raw.strip() if isinstance(raw, str) else ""
 
 
+def _clarification_text_for_run(
+    run_manifest_path: Path, report_path: Path
+) -> str:
+    """Read only the clarification input explicitly attached to this run."""
+    if not _carry_in_source_for_run(run_manifest_path):
+        return ""
+    task_root = _task_root_from_run_dir(report_path.parent.parent)
+    staged = task_root / "instruction-set" / "clarification-response.md"
+    if not staged.is_file():
+        return ""
+    try:
+        return staged.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
 def _validate_clarification_carry_in_recorded(
     data: dict,
     report_path: Path,
@@ -7066,6 +7103,11 @@ def main() -> int:
         report_path,
         failures,
         report_contracts=report_contracts,
+        run_manifest=run_manifest,
+        project_root=project_root,
+        clarification_text=_clarification_text_for_run(
+            run_manifest_path, report_path
+        ),
     )
     validation_data = report_data if isinstance(report_data, Mapping) else {}
     _validate_fix_cycle(run_manifest, validation_data, failures)