okstra 0.179.2 → 0.180.0

package/runtime/python/okstra_ctl/render.py

@@ -46,6 +46,7 @@ from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
 from .path_hints import compact_active_run_context, hydrate_run_context
 from .paths import task_timeline_file
+from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
 from .worker_artifacts import artifacts_from_context
 from .workflow import PHASE_SEQUENCE
 
@@ -1686,12 +1687,16 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     execution_identity = _execution_identity(ctx)
     payload = {
         "schemaVersion": execution_identity.get("schemaVersion", "1.0"),
+        "reportContractVersion": CURRENT_REPORT_SCHEMA_VERSION,
         "okstraVersion": ctx.get("OKSTRA_VERSION", ""),
         "projectId": ctx.get("PROJECT_ID", ""),
         "taskGroup": ctx.get("TASK_GROUP", ""),
         "taskId": ctx.get("TASK_ID", ""),
         "taskKey": ctx.get("TASK_KEY", ""),
         "taskType": ctx.get("TASK_TYPE", ""),
+        "runTimestamp": ctx.get("RUN_TIMESTAMP_ISO", ""),
+        "reportLanguage": ctx.get("REPORT_LANGUAGE", "en") or "en",
+        "leadModel": ctx.get("LEAD_MODEL", ""),
         # Every other path in this manifest is project-relative; this is the
         # anchor they resolve against. Convergence reads it to place run
         # artifacts, so a manifest without it cannot seed a round.
@@ -1763,6 +1768,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "workerPromptsDirectoryPath": ctx.get("RUN_PROMPTS_RELATIVE_PATH", ""),
         "workerPromptPathByWorkerId": worker_prompt_paths,
         "expectedReportRecordPath": ctx.get("FINAL_REPORT_RECORD_RELATIVE_PATH", ""),
+        "reportNarrativePath": ctx.get("REPORT_WRITER_NARRATIVE_RELATIVE_PATH", ""),
+        "approvalDecisionsPath": ctx.get("APPROVAL_DECISIONS_RELATIVE_PATH", ""),
+        "designPreparationPath": ctx.get("DESIGN_PREPARATION_RELATIVE_PATH", ""),
+        "planBodyVerificationPath": ctx.get("PLAN_BODY_VERIFICATION_STATE_RELATIVE_PATH", ""),
         "expectedStatusPath": ctx.get("FINAL_STATUS_RELATIVE_PATH", ""),
         "teamStatePath": ctx.get("TEAM_STATE_RELATIVE_PATH", ""),
         "activeRunContextPath": ctx.get("ACTIVE_RUN_CONTEXT_RELATIVE_PATH", ""),
@@ -1847,7 +1856,10 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         payload["analysisScopeConfirmation"] = scope_confirmation
     if ctx.get("FIX_CYCLE_ID"):
         payload["fixCycleId"] = ctx["FIX_CYCLE_ID"]
-    if ctx.get("TASK_TYPE") == "implementation-planning":
+    if (
+        CURRENT_REPORT_SCHEMA_VERSION == "3.0"
+        or ctx.get("TASK_TYPE") == "implementation-planning"
+    ):
         if not run_manifest_exists:
             payload["activityContractVersion"] = 1
         elif "activityContractVersion" in existing_run_manifest:
@@ -1864,6 +1876,27 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
     payload.update(execution_identity)
     _guard_invocation_manifest_rewrite(existing_run_manifest, payload)
     _write_json(Path(run_manifest_path), payload)
+    if CURRENT_REPORT_SCHEMA_VERSION == "3.0":
+        _initialize_report_ledgers(ctx, payload)
+
+
+def _initialize_report_ledgers(ctx: Mapping[str, Any], manifest: Mapping[str, Any]) -> None:
+    approval_value = str(ctx.get("APPROVAL_DECISIONS_PATH") or "")
+    approval_path = Path(approval_value)
+    if approval_value and not approval_path.is_file():
+        _write_json(approval_path, {
+            "schemaVersion": "1.0",
+            "owner": "lead",
+            "taskKey": manifest.get("taskKey"),
+            "taskType": manifest.get("taskType"),
+            "runSeq": (manifest.get("runSequencesByCategory") or {}).get("manifests"),
+            "activeClarifications": [],
+            "carriedDecisions": [],
+        })
+    activity_value = str(ctx.get("LEAD_EVENTS_PATH") or "")
+    activity_path = Path(activity_value)
+    if activity_value and not activity_path.is_file():
+        _write_text(activity_path, "")
 
 
 _MODEL_ASSIGNMENT_KEYS = {
@@ -1904,8 +1937,18 @@ _IMMUTABLE_INVOCATION_KEYS = (
     "workerPromptPathByWorkerId",
     "workerResultsDirectoryPath",
     "expectedReportRecordPath",
+    "reportNarrativePath",
+    "approvalDecisionsPath",
+    "designPreparationPath",
+    "planBodyVerificationPath",
     "reportTemplatePath",
 )
+_V3_REPORT_PATH_KEYS = frozenset({
+    "reportNarrativePath",
+    "approvalDecisionsPath",
+    "designPreparationPath",
+    "planBodyVerificationPath",
+})
 
 
 def _guard_invocation_manifest_rewrite(
@@ -1951,6 +1994,10 @@ def _validate_invocation_manifest(payload: Mapping[str, object]) -> None:
         item
         for item in _IMMUTABLE_INVOCATION_KEYS[4:]
         if item != "workerPromptPathByWorkerId"
+        and (
+            item not in _V3_REPORT_PATH_KEYS
+            or payload.get("reportContractVersion") == "3.0"
+        )
     ):
         if not payload.get(key):
             raise ValueError(f"incomplete invocation manifest path: {key}")

package/runtime/python/okstra_ctl/render_final_report.py

@@ -2,7 +2,7 @@
 
 The JSON SSOT lives next to the rendered markdown as
 ``final-report-<task-type>-<seq>.data.json``. Its ``schemaVersion`` selects the
-matching final-report schema. Report-writer-worker writes the data.json in
+matching final-report schema. Report assembly writes the data.json in
 Phase 6; this renderer + the matching Jinja2 template deterministically
 produce the canonical AI-facing markdown.
 
@@ -66,6 +66,7 @@ from okstra_ctl.usage_cells import format_duration_ms, format_int, format_usd
 
 TEMPLATE_BY_SCHEMA_VERSION = {
     "2.0": ("templates", "reports", "final-report-v2.template.md"),
+    "3.0": ("templates", "reports", "final-report-v2.template.md"),
 }
 DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION[CURRENT_REPORT_SCHEMA_VERSION]
 
@@ -601,8 +602,8 @@ def validate_report_language(data: dict) -> str:
     if candidate == "auto":
         raise FinalReportRenderError(
             "reportLanguage 'auto' must be resolved by the lead before "
-            "the renderer runs; the report-writer worker writes the "
-            "resolved 'en' or 'ko' into data.json.meta.reportLanguage."
+            "the renderer runs; report assembly copies the resolved 'en' or "
+            "'ko' from the run manifest into data.json.meta.reportLanguage."
         )
     if candidate not in SUPPORTED_LANGS:
         raise FinalReportRenderError(
@@ -757,9 +758,9 @@ def _with_excerpt_drift_hint(
 ) -> FinalReportRenderError:
     """Name the contract drift behind a schema failure, when that is the cause.
 
-    A long run straddles its own runtime upgrade: the report-writer authors
-    against the excerpt frozen into the bundle at prep time, while the renderer
-    validates against the installed schema. Without this the author sees only
+    A long run straddles its own runtime upgrade: the report-writer authors its
+    narrative against the excerpt frozen into the bundle at prep time, while
+    assembly and the renderer validate against the installed schema. Without this the author sees only
     `additional property ... not allowed` for a field the excerpt told it to
     write, and has no way to tell a real mistake from a stale bundle.
 

package/runtime/python/okstra_ctl/report_assembly.py

@@ -0,0 +1,354 @@
+"""역할별 리포트 입력을 검증해 계약 3.0 정본을 한 번 게시한다."""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from .agent_activity import agent_activity_rows
+from .final_report_schema import load_schema_version, validate
+from .report_inputs import ReportInputPath, report_input_paths, uses_report_contract_v3
+from .report_narrative import parse_narrative
+from .report_projections import (
+    ReportProjectionError,
+    project_convergence,
+    project_design,
+    project_execution,
+    project_token_usage,
+)
+
+
+@dataclass(frozen=True)
+class AssemblyIssue:
+    owner: str
+    artifact_path: str
+    field_path: str
+    reason: str
+
+
+class ReportAssemblyError(ValueError):
+    """게시 전 입력 검증 실패와 실제 소유자를 전달한다."""
+
+    def __init__(self, issue: AssemblyIssue) -> None:
+        self.issue = issue
+        super().__init__(
+            f"owner={issue.owner} artifactPath={issue.artifact_path} "
+            f"fieldPath={issue.field_path} reason={issue.reason}"
+        )
+
+
+def _fail(owner: str, path: Path, field: str, reason: object) -> None:
+    raise ReportAssemblyError(AssemblyIssue(owner, str(path), field, str(reason)))
+
+
+def _read_json(row: ReportInputPath) -> dict[str, Any]:
+    if not row.path.is_file():
+        _fail(row.owner, row.path, "$", "required input is missing")
+    try:
+        value = json.loads(row.path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        _fail(row.owner, row.path, "$", exc)
+    if not isinstance(value, dict):
+        _fail(row.owner, row.path, "$", "input must be a JSON object")
+    return value
+
+
+def _input_map(project_root: Path, manifest: Mapping[str, Any]) -> dict[str, ReportInputPath]:
+    try:
+        return {row.key: row for row in report_input_paths(project_root, manifest)}
+    except ValueError as exc:
+        _fail("orchestrator", project_root, "manifest", exc)
+
+
+def _narrative(row: ReportInputPath, schema: Mapping[str, Any]) -> dict[str, Any]:
+    if not row.path.is_file():
+        _fail(row.owner, row.path, "$", "required input is missing")
+    try:
+        return parse_narrative(row.path.read_text(encoding="utf-8"), schema)
+    except (OSError, UnicodeError, ValueError) as exc:
+        _fail(row.owner, row.path, "$", exc)
+
+
+def _clarifications(
+    ledger: Mapping[str, Any], activities: list[dict[str, Any]], path: Path,
+) -> list[dict[str, Any]]:
+    if ledger.get("owner") != "lead":
+        _fail("lead", path, "owner", "approval ledger owner must be lead")
+    active = ledger.get("activeClarifications")
+    if not isinstance(active, list):
+        _fail("lead", path, "activeClarifications", "must be an array")
+    for index, row in enumerate(active):
+        if not isinstance(row, Mapping):
+            _fail("lead", path, f"activeClarifications[{index}]", "must be an object")
+    activity_by_id = {row.get("activityId"): row for row in activities}
+    return [
+        _clarification_row(row, activity_by_id, path)
+        for row in active
+    ]
+
+
+def _clarification_row(
+    source: Mapping[str, Any], activities: Mapping[object, Mapping[str, Any]], path: Path,
+) -> dict[str, Any]:
+    row = {
+        key: source[key]
+        for key in (
+            "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
+            "origin", "userConfirmation", "options",
+        )
+        if key in source
+    }
+    if "approval" in source:
+        row["approvalContext"] = source["approval"]
+    resolution = source.get("resolutionInput")
+    if not isinstance(resolution, Mapping):
+        row["status"] = "open"
+        return row
+    clarification_id = source.get("id")
+    check_refs = resolution.get("checkRefs")
+    if not isinstance(check_refs, list) or not check_refs:
+        _fail("lead", path, f"{clarification_id}.resolutionInput.checkRefs", "must not be empty")
+    for activity_id in check_refs:
+        activity = activities.get(activity_id)
+        if activity is None:
+            _fail("lead", path, f"{clarification_id}.resolutionInput.checkRefs", f"unknown activity {activity_id}")
+        if clarification_id not in (activity.get("clarificationRefs") or []):
+            _fail("activity-ledger", path, str(activity_id), f"missing clarificationRefs {clarification_id}")
+    row.update(
+        status="resolved",
+        userInput=resolution.get("userText", ""),
+        resolution={
+            "disposition": resolution.get("disposition"),
+            "userText": resolution.get("userText"),
+            "checkRefs": list(check_refs),
+        },
+    )
+    return row
+
+
+def _attach_plan_backlinks(data: dict[str, Any], activities: list[dict[str, Any]]) -> None:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return
+    verification = planning.get("planBodyVerification")
+    if not isinstance(verification, dict):
+        return
+    refs_by_item: dict[str, set[str]] = {}
+    for activity in activities:
+        for item_id in activity.get("planItemIds") or []:
+            refs_by_item.setdefault(str(item_id), set()).update(
+                str(ref) for ref in activity.get("clarificationRefs") or []
+            )
+    for item in verification.get("planItems") or []:
+        if isinstance(item, dict):
+            item["clarificationRefs"] = sorted(refs_by_item.get(str(item.get("id")), set()))
+
+
+def _compose(
+    project_root: Path, manifest_path: Path, manifest: Mapping[str, Any],
+) -> dict[str, Any]:
+    schema = load_schema_version("3.0")
+    inputs = _input_map(project_root, manifest)
+    narrative = _narrative(inputs["narrative"], schema)
+    ledger = _read_json(inputs["approval-decisions"])
+    team_state = _read_json(inputs["execution-status"])
+    convergence = _read_json(inputs["convergence"])
+    if not inputs["agent-activity"].path.is_file():
+        _fail("activity-ledger", inputs["agent-activity"].path, "$", "required input is missing")
+    try:
+        activities = list(agent_activity_rows(project_root, manifest_path))
+    except ValueError as exc:
+        _fail("activity-ledger", inputs["agent-activity"].path, "$", exc)
+    try:
+        convergence_data = project_convergence(convergence)
+    except ReportProjectionError as exc:
+        _fail("convergence", inputs["convergence"].path, "$", exc)
+    try:
+        execution = project_execution(manifest, team_state)
+        usage = project_token_usage(team_state)
+    except (TypeError, ValueError) as exc:
+        _fail("team-state", inputs["execution-status"].path, "$", exc)
+    data = {"schemaVersion": "3.0", **narrative, **execution}
+    data["tokenUsage"] = usage
+    data["crossVerification"] = convergence_data["crossVerification"]
+    data["clarificationItems"] = _clarifications(ledger, activities, inputs["approval-decisions"].path)
+    data["agentActivity"] = activities
+    data["evidence"] = {"primary": _promoted_evidence(convergence_data)}
+    data["missingInformation"] = []
+    _attach_metadata(data, manifest)
+    _attach_machine_planning(data, inputs)
+    _attach_plan_backlinks(data, activities)
+    return data
+
+
+def _identity(manifest: Mapping[str, Any]) -> tuple[str, str, str]:
+    task_key = str(manifest.get("taskKey") or "")
+    parts = task_key.split(":")
+    if len(parts) >= 3:
+        return parts[0], parts[-2], parts[-1]
+    return (
+        str(manifest.get("projectId") or "unknown"),
+        str(manifest.get("taskGroup") or "unknown"),
+        str(manifest.get("taskId") or task_key or "unknown"),
+    )
+
+
+def _attach_metadata(data: dict[str, Any], manifest: Mapping[str, Any]) -> None:
+    project_id, task_group, task_id = _identity(manifest)
+    task_type = str(manifest.get("taskType") or "")
+    task_key = str(manifest.get("taskKey") or "")
+    created = str(manifest.get("runTimestamp") or manifest.get("createdAt") or "unknown")
+    data["meta"] = {"reportLanguage": str(manifest.get("reportLanguage") or "en")}
+    clarifications = data.get("clarificationItems") or []
+    blocked = any(
+        isinstance(row, Mapping) and row.get("status") in {"open", "answered"}
+        for row in clarifications
+    )
+    frontmatter = {
+        "title": f"OKSTRA Final Report - {task_key}",
+        "id": task_key.replace(":", "-"),
+        "tags": ["final-report"],
+        "status": "in-progress" if blocked else "completed",
+        "aliases": [f"{task_id}-{task_type}"],
+        "date": created,
+        "taskId": task_id,
+        "taskGroup": task_group,
+        "projectId": project_id,
+        "taskType": task_type,
+        "workerId": "report-writer",
+        "approved": False,
+    }
+    planning = data.get("implementationPlanning")
+    if isinstance(planning, Mapping) and planning.get("planningContract") == "selected-direction":
+        selected = planning.get("selectedDirectionRef")
+        frontmatter["selectedDirectionRef"] = str(
+            selected.get("snapshotPath") if isinstance(selected, Mapping) else ""
+        )
+    else:
+        frontmatter["implementationOption"] = ""
+    data["frontmatter"] = frontmatter
+    data["header"] = {
+        "taskKey": task_key,
+        "createdAt": created,
+        "taskType": task_type,
+        "reportOwner": "Okstra lead",
+        "reportAuthor": "Report writer worker",
+        "leadModel": str(manifest.get("leadModel") or "unknown"),
+        "okstraVersion": str(manifest.get("okstraVersion") or "unknown"),
+    }
+
+
+def _promoted_evidence(convergence: Mapping[str, Any]) -> list[dict[str, Any]]:
+    return [
+        {
+            "id": f"E-{index:03d}",
+            "ticketId": row["ticketId"],
+            "evidence": row["evidence"],
+            "sourceItems": row["sourceItems"],
+            "source": "convergence",
+        }
+        for index, row in enumerate(convergence.get("promotedEvidence") or [], start=1)
+    ]
+
+
+def _attach_machine_planning(
+    data: dict[str, Any], inputs: Mapping[str, ReportInputPath],
+) -> None:
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return
+    design_row = inputs.get("design-preparation")
+    if design_row is None:
+        return
+    try:
+        design = project_design(planning, _read_json(design_row))
+    except ReportProjectionError as exc:
+        _fail(design_row.owner, design_row.path, "$", exc)
+    planning["designPreparation"] = design["designPreparation"]
+    stages = {row.get("stage"): row for row in planning.get("stages") or [] if isinstance(row, dict)}
+    for coverage in design["stageCoverage"]:
+        stage = stages.get(coverage.get("stage"))
+        if stage is not None:
+            stage["designSurfaceCoverage"] = coverage.get("rows") or []
+    verification_row = inputs.get("plan-body-verification")
+    if verification_row is None:
+        return
+    verification = _read_json(verification_row)
+    if verification.get("owner") != "convergence":
+        _fail(
+            verification_row.owner, verification_row.path, "owner",
+            "plan-body verification owner must be convergence",
+        )
+    projection = verification.get("planBodyVerification")
+    if not isinstance(projection, Mapping):
+        _fail(
+            verification_row.owner, verification_row.path,
+            "planBodyVerification", "must be an object",
+        )
+    planning["planBodyVerification"] = dict(projection)
+
+
+def _schema_owner(error: str) -> str:
+    field = error.split(" ", 1)[0]
+    owners = {
+        "executionStatus": "team-state",
+        "tokenUsage": "team-state",
+        "crossVerification": "convergence",
+        "clarificationItems": "lead",
+        "agentActivity": "activity-ledger",
+        "executionRoles": "run-manifest",
+        "frontmatter": "orchestrator",
+        "header": "orchestrator",
+        "meta": "orchestrator",
+    }
+    if "designPreparation" in error or "designSurfaceCoverage" in error:
+        return "design-surface-detector"
+    if "planBodyVerification" in error:
+        return "convergence"
+    if "selectedDirectionRef" in error:
+        return "report-writer"
+    return owners.get(field.split(".", 1)[0], "report-writer")
+
+
+def _publish(
+    target: Path, data: Mapping[str, Any], replace: Callable[[str, str], None],
+) -> None:
+    target.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, name = tempfile.mkstemp(prefix=f".{target.name}.", dir=target.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(data, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        replace(name, str(target))
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def assemble_report(
+    project_root: Path, manifest_path: Path, *,
+    replace: Callable[[str, str], None] = os.replace,
+) -> dict[str, Any]:
+    """모든 입력이 유효할 때만 계약 3.0 정본을 한 번 교체한다."""
+    manifest_row = ReportInputPath("run-manifest", "orchestrator", manifest_path)
+    manifest = _read_json(manifest_row)
+    if not uses_report_contract_v3(manifest):
+        _fail("orchestrator", manifest_path, "reportContractVersion", "requires 3.0")
+    data = _compose(project_root, manifest_path, manifest)
+    errors = validate(data, load_schema_version("3.0"))
+    if errors:
+        target = Path(str(manifest.get("expectedReportRecordPath") or "data.json"))
+        target = target if target.is_absolute() else project_root / target
+        _fail(_schema_owner(errors[0]), target, errors[0].split(" ", 1)[0], errors[0])
+    value = manifest.get("expectedReportRecordPath")
+    if not isinstance(value, str) or not value:
+        _fail("orchestrator", manifest_path, "expectedReportRecordPath", "required")
+    target = Path(value)
+    target = target if target.is_absolute() else project_root / target
+    _publish(target, data, replace)
+    return data

package/runtime/python/okstra_ctl/report_contract.py

@@ -2,7 +2,8 @@
 from __future__ import annotations
 
 
-CURRENT_REPORT_SCHEMA_VERSION = "2.0"
+CURRENT_REPORT_SCHEMA_VERSION = "3.0"
+LATEST_REPORT_SCHEMA_VERSION = "3.0"
 
 PUBLIC_REPORT_TASK_TYPES = (
     "requirements-discovery",