okstra 0.144.0 → 0.146.0

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -0,0 +1,369 @@
+"""Shared evidence resolution for read-only analysis sidetracks."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from .final_report_paths import final_report_data_path
+from .paths import task_manifest_file
+from .user_response import (
+    UserResponseError,
+    load_authoritative_analysis_review,
+)
+
+
+ANALYSIS_TASK_TYPES = (
+    "project-analysis",
+    "feature-analysis",
+    "change-impact-analysis",
+)
+
+
+class AnalysisInputError(ValueError):
+    """Raised when a report cannot safely serve as analysis evidence."""
+
+
+@dataclass(frozen=True)
+class AnalysisReportCandidate:
+    report_path: Path
+    task_key: str
+    task_type: str
+    created_at: str
+    run_seq: str
+    source_commit: str
+    review_status: str
+    feature_index: tuple[object, ...]
+
+
+@dataclass(frozen=True)
+class ResolvedEvidenceInput:
+    report_path: Path
+    task_key: str
+    task_type: str
+    run_seq: str
+    source_commit: str
+    review_status: str
+    relation: str
+    freshness: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "taskKey": self.task_key,
+            "taskType": self.task_type,
+            "reportPath": str(self.report_path),
+            "runSeq": self.run_seq,
+            "sourceCommit": self.source_commit,
+            "relation": self.relation,
+            "freshness": self.freshness,
+            "reviewStatus": self.review_status,
+        }
+
+
+_EVIDENCE_RELATION_BY_TYPES = {
+    ("feature-analysis", "project-analysis"): "project-context",
+    ("change-impact-analysis", "project-analysis"): "project-context",
+    ("change-impact-analysis", "feature-analysis"): "feature-baseline",
+}
+_REPORT_NAME_RE = re.compile(r"^final-report-.+-(?P<run_seq>[^-]+)\.md$")
+_FEATURE_ID_RE = re.compile(r"PF-\d{3}")
+_FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
+_RUN_SEQ_RE = re.compile(r"[0-9]{3}")
+_CREATED_AT_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z")
+
+
+def parse_evidence_paths(
+    raw_paths: str, project_root: Path | None = None,
+) -> tuple[Path, ...]:
+    """Parse a comma-separated evidence selection in its supplied order."""
+    root = project_root.resolve() if project_root else None
+    paths: list[Path] = []
+    for raw_path in raw_paths.split(","):
+        value = raw_path.strip()
+        if not value:
+            continue
+        path = Path(value).expanduser()
+        if root and not path.is_absolute():
+            path = root / path
+        paths.append(path.resolve())
+    return tuple(paths)
+
+
+def load_candidate_map(
+    project_root: Path, report_paths: Sequence[Path],
+) -> dict[Path, AnalysisReportCandidate]:
+    """Load canonical metadata for every explicitly selected report."""
+    return {
+        candidate.report_path: candidate
+        for candidate in (
+            load_analysis_report_candidate(project_root, report_path)
+            for report_path in report_paths
+        )
+    }
+
+
+def resolve_analysis_head(analysis_root: Path, task_type: str = "") -> str:
+    """Return an analysis worktree's immutable HEAD, or reject an invalid one."""
+    if task_type and task_type not in ANALYSIS_TASK_TYPES:
+        return ""
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(analysis_root), "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise AnalysisInputError(
+            f"cannot resolve analysis source commit: {analysis_root}"
+        ) from exc
+    return _validated_commit(result.stdout.strip(), "analysis source commit")
+
+
+def _resolved_within(path: Path, root: Path, description: str) -> Path:
+    resolved = path.resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise AnalysisInputError(f"{description} must be under {root}") from exc
+    return resolved
+
+
+def _required_string(data: Mapping[str, object], key: str, context: str) -> str:
+    value = data.get(key)
+    if not isinstance(value, str) or not value:
+        raise AnalysisInputError(f"data.json {context}.{key} must be a non-empty string")
+    return value
+
+
+def _validated_commit(value: str, field: str) -> str:
+    if not _FULL_COMMIT_RE.fullmatch(value):
+        raise AnalysisInputError(
+            f"{field} must be a 40-character lowercase hexadecimal commit"
+        )
+    return value
+
+
+def _validated_created_at(value: str) -> str:
+    if _CREATED_AT_RE.fullmatch(value) is None:
+        raise AnalysisInputError(
+            "data.json header.createdAt must use YYYY-MM-DDTHH:MM:SSZ"
+        )
+    try:
+        datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
+    except ValueError as exc:
+        raise AnalysisInputError("data.json header.createdAt is invalid") from exc
+    return value
+
+
+def _report_path_metadata(project_root: Path, report_path: Path) -> tuple[Path, str, str]:
+    okstra_root = project_root.resolve() / ".okstra"
+    relative = report_path.relative_to(okstra_root)
+    parts = relative.parts
+    if (
+        len(parts) != 7
+        or parts[0] != "tasks"
+        or parts[3] != "runs"
+        or parts[5] != "reports"
+    ):
+        raise AnalysisInputError("report path is not an analysis run report")
+    return report_path.parents[3], parts[4], parts[6]
+
+
+def _task_key_from_manifest(task_root: Path, okstra_root: Path) -> str:
+    manifest_path = _resolved_within(
+        task_manifest_file(task_root), okstra_root, "task manifest path"
+    )
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise AnalysisInputError(f"cannot read task manifest: {manifest_path}") from exc
+    if not isinstance(manifest, dict):
+        raise AnalysisInputError("task manifest must contain an object")
+    return _required_string(manifest, "taskKey", "task manifest")
+
+
+def load_analysis_report_candidate(
+    project_root: Path, report_path: Path
+) -> AnalysisReportCandidate:
+    """Load one report only after validating its path and canonical metadata."""
+    root = project_root.resolve()
+    okstra_root = root / ".okstra"
+    report = _resolved_within(report_path, okstra_root, "report path")
+    if not report.is_file():
+        raise AnalysisInputError(f"report does not exist: {report}")
+    task_root, path_task_type, filename = _report_path_metadata(root, report)
+    filename_match = _REPORT_NAME_RE.fullmatch(filename)
+    if not filename_match:
+        raise AnalysisInputError("report filename is not a final report")
+    data_path = _resolved_within(final_report_data_path(report), okstra_root, "data.json path")
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise AnalysisInputError(f"cannot read data.json: {data_path}") from exc
+    if not isinstance(data, dict):
+        raise AnalysisInputError("data.json must contain an object")
+    header = data.get("header")
+    common = data.get("analysisCommon")
+    if not isinstance(header, dict) or not isinstance(common, dict):
+        raise AnalysisInputError("data.json requires header and analysisCommon objects")
+    task_key = _required_string(header, "taskKey", "header")
+    task_type = _required_string(header, "taskType", "header")
+    created_at = _validated_created_at(
+        _required_string(header, "createdAt", "header")
+    )
+    run_seq = _required_string(common, "runSeq", "analysisCommon")
+    if not _RUN_SEQ_RE.fullmatch(run_seq):
+        raise AnalysisInputError("data.json analysisCommon.runSeq must be 3-digit")
+    source_commit = _validated_commit(
+        _required_string(common, "sourceCommit", "analysisCommon"),
+        "sourceCommit",
+    )
+    if task_key != _task_key_from_manifest(task_root, okstra_root):
+        raise AnalysisInputError("data.json header.taskKey does not match task manifest")
+    if task_type != path_task_type:
+        raise AnalysisInputError("data.json header.taskType does not match report path")
+    if filename != f"final-report-{task_type}-{run_seq}.md":
+        raise AnalysisInputError("data.json analysisCommon.runSeq does not match report filename")
+    feature_index: Sequence[object] = ()
+    if task_type == "project-analysis":
+        project_analysis = data.get("projectAnalysis")
+        if not isinstance(project_analysis, dict):
+            raise AnalysisInputError("data.json projectAnalysis must be an object")
+        feature_index = project_analysis.get("featureIndex")
+        if not isinstance(feature_index, list):
+            raise AnalysisInputError(
+                "data.json projectAnalysis.featureIndex must be a list"
+            )
+    try:
+        review = load_authoritative_analysis_review(
+            report,
+            expected_task_key=task_key,
+            expected_task_type=task_type,
+        )
+    except UserResponseError as exc:
+        raise AnalysisInputError(f"invalid review sidecar: {exc}") from exc
+    review_status = review.status if review is not None else "unreviewed"
+    return AnalysisReportCandidate(
+        report_path=report,
+        task_key=task_key,
+        task_type=task_type,
+        created_at=created_at,
+        run_seq=run_seq,
+        source_commit=source_commit,
+        review_status=review_status,
+        feature_index=tuple(feature_index),
+    )
+
+
+def list_evidence_candidates(
+    project_root: Path, consumer_task_type: str, relation: str
+) -> list[AnalysisReportCandidate]:
+    """Return accepted, compatible reports in deterministic newest-first order."""
+    root = project_root.resolve()
+    compatible_types = [
+        source_type
+        for (consumer, source_type), allowed_relation in _EVIDENCE_RELATION_BY_TYPES.items()
+        if consumer == consumer_task_type and allowed_relation == relation
+    ]
+    if not compatible_types:
+        return []
+    reports_root = root / ".okstra" / "tasks"
+    candidates: list[AnalysisReportCandidate] = []
+    for report in reports_root.glob("*/*/runs/*/reports/*.md"):
+        try:
+            candidate = load_analysis_report_candidate(root, report)
+        except AnalysisInputError:
+            continue
+        if candidate.task_type in compatible_types and candidate.review_status == "accepted":
+            candidates.append(candidate)
+    candidates.sort(
+        key=lambda candidate: (
+            candidate.task_key,
+            -int(candidate.run_seq),
+            str(candidate.report_path),
+        )
+    )
+    candidates.sort(key=lambda candidate: candidate.created_at, reverse=True)
+    return candidates
+
+
+def resolve_evidence_inputs(
+    project_root: Path,
+    consumer_task_type: str,
+    report_paths: Sequence[Path],
+    current_commit: str,
+) -> tuple[ResolvedEvidenceInput, ...]:
+    """Validate the explicit evidence selection that a consumer will use."""
+    _validated_commit(current_commit, "current_commit")
+    resolved: list[ResolvedEvidenceInput] = []
+    seen: set[Path] = set()
+    for report_path in report_paths:
+        candidate = load_analysis_report_candidate(project_root, report_path)
+        if candidate.report_path in seen:
+            raise AnalysisInputError(f"duplicate evidence report: {candidate.report_path}")
+        seen.add(candidate.report_path)
+        relation = _EVIDENCE_RELATION_BY_TYPES.get(
+            (consumer_task_type, candidate.task_type)
+        )
+        if relation is None:
+            raise AnalysisInputError(
+                f"evidence relation is not allowed: {consumer_task_type} <- {candidate.task_type}"
+            )
+        if candidate.review_status in {"revision-requested", "rejected"}:
+            raise AnalysisInputError(
+                f"evidence report has {candidate.review_status} review status"
+            )
+        resolved.append(ResolvedEvidenceInput(
+            report_path=candidate.report_path,
+            task_key=candidate.task_key,
+            task_type=candidate.task_type,
+            run_seq=candidate.run_seq,
+            source_commit=candidate.source_commit,
+            review_status=("accepted" if candidate.review_status == "accepted" else "user-unverified"),
+            relation=relation,
+            freshness="exact" if candidate.source_commit == current_commit else "stale",
+        ))
+    return tuple(resolved)
+
+
+def resolve_analysis_target(
+    raw_target: str,
+    evidence_inputs: Sequence[ResolvedEvidenceInput],
+    candidates: Mapping[Path, AnalysisReportCandidate],
+) -> dict[str, object]:
+    """Normalize a feature-index identifier or a non-empty free-text target."""
+    target = raw_target.strip()
+    if not target:
+        raise AnalysisInputError("analysis target must not be empty")
+    if not _FEATURE_ID_RE.fullmatch(target):
+        return {"inputMode": "free-text", "requestedValue": target}
+    matches: list[dict[object, object]] = []
+    for evidence in evidence_inputs:
+        if evidence.relation != "project-context":
+            continue
+        candidate = candidates.get(evidence.report_path)
+        if candidate is None:
+            candidate = next(
+                (value for path, value in candidates.items() if path.resolve() == evidence.report_path),
+                None,
+            )
+        if candidate is None:
+            continue
+        matches.extend(
+            feature for feature in candidate.feature_index
+            if isinstance(feature, dict) and feature.get("id") == target
+        )
+    if len(matches) != 1:
+        raise AnalysisInputError(
+            f"exactly one project-context feature must match {target}"
+        )
+    return {
+        "inputMode": "feature-index",
+        "requestedValue": target,
+        "feature": dict(matches[0]),
+    }

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -20,7 +20,7 @@ BRIEF_SECTIONS = (
     "Task Continuity Notes",
     "Available MCP Servers",
 )
-ERROR_ANALYSIS_BRIEF_SECTIONS = (
+CANONICAL_BRIEF_SECTIONS = (
     "Source Material",
     "Context",
     "Problem / Symptom",
@@ -38,9 +38,6 @@ ERROR_ANALYSIS_BRIEF_SECTIONS = (
     "Reporter Confirmations",
     "Augmentation",
 ) + BRIEF_SECTIONS
-BRIEF_SECTIONS_BY_TASK_TYPE = {
-    "error-analysis": ERROR_ANALYSIS_BRIEF_SECTIONS,
-}
 PROFILE_SECTIONS = (
     "Primary focus areas",
     "Expected output emphasis",
@@ -101,7 +98,7 @@ def build_analysis_packet(
             bool(clarification_response_path),
         )
     )
-    parts.extend(_brief_block(task_type, brief_text))
+    parts.extend(_brief_block(brief_text))
     parts.extend(_profile_block(task_type, profile_text))
     parts.extend(_reference_block(reference_text))
     parts.extend(_fix_history_block(fix_history_text))
@@ -160,15 +157,12 @@ def _intro_block(
     return lines
 
 
-def _brief_block(task_type: str, brief_text: str) -> list[str]:
+def _brief_block(brief_text: str) -> list[str]:
     return [
         "",
         "## Task-Specific Brief Extract",
         "",
-        _extract_sections(
-            brief_text,
-            BRIEF_SECTIONS_BY_TASK_TYPE.get(task_type, BRIEF_SECTIONS),
-        ),
+        _extract_sections(brief_text, CANONICAL_BRIEF_SECTIONS),
     ]
 
 

package/runtime/python/okstra_ctl/clarification_items.py

@@ -372,6 +372,79 @@ def user_response_sidecars(source: Path) -> list[Path]:
     )
 
 
+_ANALYSIS_REPORT_NAME_RE = re.compile(
+    r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+)
+_SIDECAR_FRONTMATTER_RE = re.compile(
+    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
+    re.DOTALL,
+)
+_ANALYSIS_REVIEW_HEADING_RE = re.compile(
+    r"^## ANALYSIS REVIEW\s*$", re.MULTILINE
+)
+
+
+def _sidecar_frontmatter_value(text: str, key: str) -> str:
+    match = _SIDECAR_FRONTMATTER_RE.match(text)
+    if match is None:
+        return ""
+    value = re.search(
+        rf"^{re.escape(key)}:\s*(\S.*?)\s*$",
+        match.group("body"),
+        re.MULTILINE,
+    )
+    return value.group(1) if value else ""
+
+
+def _sidecars_for_attachment(source: Path) -> list[Path]:
+    sidecars = user_response_sidecars(source)
+    report_match = _ANALYSIS_REPORT_NAME_RE.fullmatch(source.name)
+    if report_match is None:
+        return sidecars
+    expected_source = (
+        f"runs/{report_match.group('task_type')}/reports/{source.name}"
+    )
+    ordinary: list[Path] = []
+    candidates: list[tuple[Path, str]] = []
+    for sidecar in sidecars:
+        try:
+            text = sidecar.read_text(encoding="utf-8")
+        except OSError:
+            ordinary.append(sidecar)
+            continue
+        if _ANALYSIS_REVIEW_HEADING_RE.search(text) is None:
+            ordinary.append(sidecar)
+            continue
+        source_report = _sidecar_frontmatter_value(text, "source-report")
+        seq = _sidecar_frontmatter_value(text, "seq")
+        if source_report and source_report != expected_source:
+            continue
+        if seq and seq != report_match.group("seq"):
+            continue
+        candidates.append((sidecar, text))
+
+    from okstra_ctl.user_response import UserResponseError, parse_analysis_review
+
+    valid: list[Path] = []
+    malformed: list[Path] = []
+    for sidecar, text in candidates:
+        try:
+            review = parse_analysis_review(text)
+        except UserResponseError:
+            malformed.append(sidecar)
+            continue
+        if review is not None and (
+            review.source_report == expected_source
+            and review.seq == report_match.group("seq")
+        ):
+            valid.append(sidecar)
+        else:
+            malformed.append(sidecar)
+    selected = valid if valid else malformed
+    return sorted([*ordinary, *selected])
+
+
 def _sidecar_answers(source: Path) -> dict[str, str]:
     """`user-responses/` 사이드카들의 답변을 `{clarification-id: value}` 로 모은다.
 
@@ -399,7 +472,7 @@ def attached_user_responses_section(source: Path) -> str:
     첨부할 때 쓴다. `clarification_response_with_sidecars` 와 같은 직렬화 포맷을
     한 곳에서 만들어 두 carry-in 경로가 갈라지지 않게 한다.
     """
-    sidecars = user_response_sidecars(source)
+    sidecars = _sidecars_for_attachment(source)
     if not sidecars:
         return ""
     parts = ["# Attached User Responses\n"]