okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/report_assembly.py

@@ -8,7 +8,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
-from .agent_activity import agent_activity_rows
+from .agent.activity import agent_activity_rows
 from .clarification_items import (
     clarification_disposition,
     incorporated_clarification_ids,
@@ -22,6 +22,13 @@ from .report_synthesis_packet import (
     report_synthesis_packet_paths,
     verify_report_synthesis_packet_sources,
 )
+from .conformance import strip_stage_declaration_label
+from .design_prep import DesignPrepError, materialize_design_prep_requests
+from .implementation_direction import (
+    load_selected_direction_snapshot,
+    validate_selected_direction_plan,
+)
+from .paths import task_dir
 from .report_projections import (
     ReportProjectionError,
     project_convergence,
@@ -29,6 +36,8 @@ from .report_projections import (
     project_execution,
     project_token_usage,
 )
+from .scope_provenance import parse_source
+from .verification_target import read_verification_target
 
 
 @dataclass(frozen=True)
@@ -174,7 +183,7 @@ def _carried_clarification_row(source: Mapping[str, Any]) -> dict[str, Any]:
         key: source[key]
         for key in (
             "id", "ticketId", "kind", "statement", "expectedForm", "blocks",
-            "origin", "userConfirmation", "options",
+            "origin", "userConfirmation", "userInput", "options",
         )
         if key in source
     }
@@ -182,8 +191,12 @@ def _carried_clarification_row(source: Mapping[str, Any]) -> dict[str, Any]:
         row["approvalContext"] = source["approval"]
     resolution = source.get("resolutionInput")
     if not isinstance(resolution, Mapping):
-        row["status"] = "resolved"
-        return row
+        # `resolved` 가 아니라 `answered` 다. 스키마는 `resolved` 에 `resolution`
+        # 을 요구하고 그 `checkRefs` 는 **이번 run** 의 활동 행(`A-NNN`)인데,
+        # 이월된 답에는 이번 run 의 활동이 없다 — `resolved` 로 쓰면 통과 가능한
+        # 값이 없는 행이 된다. 답이 있었다는 사실은 `userInput` 이 나른다.
+        row["status"] = "answered"
+        return _neutralize_carried_approval_block(row)
     row.update(
         status="resolved",
         userInput=resolution.get("userText", ""),
@@ -193,6 +206,15 @@ def _carried_clarification_row(source: Mapping[str, Any]) -> dict[str, Any]:
             "checkRefs": list(resolution.get("checkRefs") or []),
         },
     )
+    return _neutralize_carried_approval_block(row)
+
+
+def _neutralize_carried_approval_block(row: dict[str, Any]) -> dict[str, Any]:
+    """이월 행은 이미 반영된 답이다. Blocks=approval 을 그대로 올리면
+    역추적이 없는 승인 차단이 다시 생긴다."""
+    if row.get("blocks") == "approval":
+        row["blocks"] = "none"
+        row.pop("approvalContext", None)
     return row
 
 
@@ -256,11 +278,77 @@ def _latest_user_response_value(
     return _project_relative(project_root, responses[-1])
 
 
+def _run_inputs_clarification_response(manifest_path: Path) -> str:
+    """이 run 을 띄운 carry-in 경로를 per-run `run-inputs-*.json` 에서 읽는다.
+
+    같은 사용자 입력을 두 소비자가 서로 다른 파일에서 찾고 있었다.
+    `validate-run` 의 `_carry_in_source_for_run` 은 run-inputs 를 보며 그
+    독스트링이 "run-inputs 기록이 유일한 per-run 증거"라고 적어 두는데, 조립은
+    매니페스트와 active-run-context 만 봤다. 두 곳 다 비어 있는 phase 에서는
+    조립이 `clarificationCarryIn` 을 만들지 않고 검증기는 없다고 실패시킨다 —
+    실측(2026-08-26, `fontsninja-nlpvibe` final-verification): 매니페스트에
+    키 없음, active-run-context 의 `instructionSet` 이 `null`, run-inputs 에는
+    값 있음. carry-in 을 붙여 실행한 run 이 구조적으로 실패했다. 그 필드는
+    조립 소유라 작성자가 교정 라운드로도 못 넘는다.
+    """
+    name = manifest_path.name
+    if not name.startswith("run-manifest-") or not name.endswith(".json"):
+        return ""
+    inputs_path = manifest_path.with_name(
+        name.replace("run-manifest-", "run-inputs-", 1)
+    )
+    if not inputs_path.is_file():
+        return ""
+    try:
+        payload = load_owned_object(inputs_path, artifact="run inputs")
+    except (JsonBoundaryError, OSError):
+        return ""
+    inputs = payload.get("inputs") if isinstance(payload, Mapping) else None
+    value = (
+        inputs.get("clarificationResponsePath") if isinstance(inputs, Mapping) else None
+    )
+    return value.strip() if isinstance(value, str) else ""
+
+
+def _verification_scope(project_root: Path, manifest: Mapping[str, Any]) -> str:
+    """이 run 이 검증한 범위 — 준비된 target 스냅샷이 정본이다.
+
+    이 필드는 읽는 쪽만 있고 쓰는 쪽이 없었다. `handoff record-verified` 와
+    `report_finalize` 의 teardown 분기가 읽고, `validate-run` 은 target 과
+    대조한다. 그런데 서술문 스키마에 속성이 없어 작성자가 저작할 수 없고
+    조립도 만들지 않았다 — 그래서 값은 언제나 비었고, 세 소비자가 전부 조용히
+    엉뚱하게 동작했다: `record-verified` 는 항상 거부하고, teardown 은 항상
+    건너뛰고, target 대조는 `actual` 이 비어 아예 비교되지 않았다. 실측
+    (2026-08-26, `fontsninja-nlpvibe` final-verification): 리포트는 수락인데
+    `consumers.jsonl` 의 verified 행은 0건인 채로 run 이 `passed` 로 닫혔다.
+
+    작성자의 것이 아니라는 것은 프로필이 이미 못박고 있다 — "`verificationScope`
+    in particular gates both stage-group eligibility and release-handoff routing,
+    so it is not the report's to restate". 그래서 조립이 target 에서 읽어 싣는다.
+    다이제스트가 안 맞는 스냅샷은 `read_verification_target` 이 ``None`` 을
+    돌려주므로 그때는 값을 만들지 않는다 — 변조된 근거로 라우팅을 여는 것보다
+    비어 있는 편이 낫다.
+    """
+    instruction_set = manifest.get("instructionSet")
+    relative = (
+        str(instruction_set.get("verificationTargetPath") or "").strip()
+        if isinstance(instruction_set, Mapping)
+        else ""
+    )
+    if not relative:
+        return ""
+    target = read_verification_target(project_root, relative)
+    return str((target or {}).get("scope") or "").strip()
+
+
 def _clarification_carry_in(
     project_root: Path,
     manifest: Mapping[str, Any],
+    manifest_path: Path,
 ) -> dict[str, str] | None:
-    value = _clarification_response_value(project_root, manifest)
+    value = _clarification_response_value(project_root, manifest) or (
+        _run_inputs_clarification_response(manifest_path)
+    )
     if not value:
         return None
     path = Path(value)
@@ -358,18 +446,118 @@ def _compose(
     data["tokenUsage"] = usage
     data["crossVerification"] = convergence_data["crossVerification"]
     data["clarificationItems"] = _clarifications(ledger, activities, inputs["approval-decisions"].path)
-    carry_in = _clarification_carry_in(project_root, manifest)
+    carry_in = _clarification_carry_in(project_root, manifest, manifest_path)
     if carry_in is not None:
         data["clarificationCarryIn"] = carry_in
+    scope = _verification_scope(project_root, manifest)
+    if scope:
+        data["verificationScope"] = scope
     data["agentActivity"] = activities
     data["evidence"] = {"primary": _promoted_evidence(convergence_data)}
     data["missingInformation"] = []
+    # 스냅샷 복사가 _attach_metadata 보다 먼저다 — frontmatter 가
+    # selectedDirectionRef.snapshotPath 를 읽는다.
+    _apply_selected_direction_snapshot(data, project_root, manifest)
     _attach_metadata(data, manifest)
     _attach_machine_planning(data, inputs)
     _attach_plan_backlinks(data, activities)
+    _fill_end_state_coverage(data)
     return data
 
 
+def _selected_direction_inputs(
+    project_root: Path, manifest: Mapping[str, Any]
+) -> tuple[Path, Path]:
+    """구현 진입(run.py `_validate_selected_implementation_plan`)과 같은 경로."""
+    _project_id, task_group, task_id = _identity(manifest)
+    instruction_set = task_dir(project_root, task_group, task_id) / "instruction-set"
+    return (
+        instruction_set / "selected-direction.json",
+        instruction_set / "task-brief.md",
+    )
+
+
+def _apply_selected_direction_snapshot(
+    data: dict[str, Any], project_root: Path, manifest: Mapping[str, Any]
+) -> None:
+    """selected-direction 계획의 기계 복사 필드를 스냅샷 원문으로 채운다.
+
+    `directionRealization` 의 4필드는 `!=` 완전 일치가 계약인데
+    (implementation_direction `_direction_realization_errors`) writer 가
+    의역하는 실측 실패가 있었다(dev-10341, 4필드 전부). 판단이 없는 복사는
+    조립 소유다 — `_attach_machine_planning` 이 design-prep 투영을 소유하는
+    것과 같은 근거. `conformanceTests` 의 `stage-<N> — ` 라벨 잔류도 같은
+    계급이라 여기서 뗀다.
+    """
+    planning = data.get("implementationPlanning")
+    if (
+        not isinstance(planning, dict)
+        or planning.get("planningContract") != "selected-direction"
+    ):
+        return
+    snapshot_path, _brief_path = _selected_direction_inputs(project_root, manifest)
+    snapshot, load_failures = load_selected_direction_snapshot(snapshot_path)
+    if snapshot is None:
+        _fail(
+            "orchestrator", snapshot_path,
+            "implementationPlanning.selectedDirectionRef",
+            "; ".join(load_failures),
+        )
+    # selectedDirectionRef 5필드도 전부 기계 유도값이다 — sourceReport /
+    # sourceDataSha256 / optionId 는 스냅샷 본문에, 경로·해시는 스냅샷
+    # 실물에 있다. run 001 실측에서 writer 가 snapshotPath 를 틀렸다.
+    planning["selectedDirectionRef"] = {
+        "sourceReport": snapshot.data.get("sourceReport"),
+        "sourceDataSha256": snapshot.data.get("sourceDataSha256"),
+        "optionId": snapshot.data.get("optionId"),
+        "snapshotPath": snapshot.relative_path,
+        "snapshotSha256": snapshot.sha256,
+    }
+    realization = planning.get("directionRealization")
+    direction = snapshot.data.get("direction")
+    if isinstance(realization, dict) and isinstance(direction, Mapping):
+        realization["coreMechanism"] = direction.get("coreMechanism")
+        realization["architectureBoundaries"] = direction.get(
+            "architectureBoundaries"
+        )
+        realization["planningInvariants"] = snapshot.data.get("planningInvariants")
+        realization["userConstraints"] = snapshot.data.get("userConstraints")
+    for stage in planning.get("stages") or []:
+        if not isinstance(stage, dict):
+            continue
+        declared = stage.get("conformanceTests")
+        number = stage.get("stage")
+        if (
+            isinstance(declared, str)
+            and isinstance(number, int)
+            and not isinstance(number, bool)
+            and number >= 1
+        ):
+            stage["conformanceTests"] = strip_stage_declaration_label(
+                number, declared
+            )
+
+
+def _selected_direction_publication_errors(
+    data: Mapping[str, Any], project_root: Path, manifest: Mapping[str, Any]
+) -> list[str]:
+    """게시 직전에 구현 진입 검증을 그대로 돌린다.
+
+    같은 검증이 말미 validate-run 에서는 advisory 로만 나와, 통과 발행된
+    계획이 구현 진입(run.py:1445)에서 처음 하드 거부되는 실측 wedge 가
+    있었다(dev-10341, 17건). 게시 시점 실패는 writer/lead 가 run 안에서
+    고칠 수 있다.
+    """
+    planning = data.get("implementationPlanning")
+    if (
+        not isinstance(planning, Mapping)
+        or planning.get("planningContract") != "selected-direction"
+    ):
+        return []
+    snapshot_path, brief_path = _selected_direction_inputs(project_root, manifest)
+    return validate_selected_direction_plan(data, brief_path, snapshot_path)
+
+
 def _identity(manifest: Mapping[str, Any]) -> tuple[str, str, str]:
     task_key = str(manifest.get("taskKey") or "")
     parts = task_key.split(":")
@@ -481,6 +669,84 @@ def _attach_machine_planning(
             "planBodyVerification", "must be an object",
         )
     planning["planBodyVerification"] = dict(projection)
+    _sync_human_summary_with_plan_body_gate(data, projection)
+
+
+def _sync_human_summary_with_plan_body_gate(
+    data: dict[str, Any], projection: Mapping[str, Any],
+) -> None:
+    """게이트가 통과했는데 내러티브가 unseeded 로 남으면 사람용 칸을 맞춘다.
+
+    report-writer 는 PBV 전에 쓰고, 조립이 게이트를 덮어씌운다. blockers 와
+    nextStep 이 그때의 문장을 그대로 두면 통과한 계획이 아직 검증 전으로 보인다.
+    """
+    gate = str(projection.get("gateResult") or "")
+    if gate not in {"passed", "passed-with-dissent"}:
+        return
+    summary = data.get("humanSummary")
+    if isinstance(summary, dict) and isinstance(summary.get("blockers"), list):
+        summary["blockers"] = [
+            row for row in summary["blockers"]
+            if "unseeded" not in str(row).lower()
+        ]
+    card = data.get("verdictCard")
+    if not isinstance(card, dict):
+        return
+    next_step = str(card.get("nextStep") or "")
+    lowered = next_step.lower()
+    if "unseeded" not in lowered and "seed" not in lowered:
+        return
+    next_step = (
+        "Plan-body verification passed. Do not start implementation "
+        "until `frontmatter.approved` is true."
+    )
+    card["nextStep"] = next_step
+    final = data.get("finalVerdict")
+    if isinstance(final, dict):
+        final["nextStep"] = next_step
+
+
+def _fill_end_state_coverage(data: dict[str, Any]) -> None:
+    """writer 가 못 쓴 endStateCoverage 를 requirementCoverage brief:EB-001 에서 채운다.
+
+    내러티브 스키마가 이 칸을 열어 주면 writer 가 쓸 수 있다. 비어 있으면
+    validate-run 이 brief id 마다 한 행을 요구하므로 조립이 채운다.
+    """
+    existing = data.get("endStateCoverage")
+    if isinstance(existing, list) and existing:
+        return
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        return
+    derived = _end_state_rows_from_requirement_coverage(planning)
+    if derived:
+        data["endStateCoverage"] = derived
+
+
+def _end_state_rows_from_requirement_coverage(
+    planning: Mapping[str, Any],
+) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for item in planning.get("requirementCoverage") or []:
+        if not isinstance(item, Mapping):
+            continue
+        ref = parse_source(str(item.get("source") or ""))
+        if not ref.is_end_state_id or ref.value in seen:
+            continue
+        seen.add(ref.value)
+        status = str(item.get("status") or "")
+        row: dict[str, Any] = {
+            "id": ref.value,
+            "disposition": "addressed" if status == "covered" else "deferred",
+            "coveredBy": str(item.get("id") or item.get("coveredBy") or ""),
+        }
+        if row["disposition"] != "addressed":
+            row["rationale"] = (
+                f"requirementCoverage `{item.get('id')}` status is `{status or 'empty'}`."
+            )
+        rows.append(row)
+    return rows
 
 
 def _schema_owner(error: str) -> str:
@@ -522,6 +788,20 @@ def _publish(
             os.unlink(name)
 
 
+def _materialize_planning_requests(target: Path) -> None:
+    """게시한 계획 기록에서 Okstra 소유 design-prep 요청을 만든다.
+
+    계약 3.0 은 token-usage 에서 `--substitute-data` 를 빼므로, v2 가
+    populate_token_cells 안에서 하던 생성을 조립이 맡는다.
+    """
+    if not target.name.startswith("final-report-implementation-planning-"):
+        return
+    try:
+        materialize_design_prep_requests(target)
+    except DesignPrepError as exc:
+        _fail("orchestrator", target, "designPreparation", exc)
+
+
 def assemble_report(
     project_root: Path, manifest_path: Path, *,
     replace: Callable[[str, str], None] = os.replace,
@@ -557,13 +837,16 @@ def assemble_report(
         raise ReportAssemblyError(tuple(input_issues))
     data = _compose(project_root, manifest_path, manifest, inputs, schema)
     errors = validate(data, schema)
+    direction_errors = _selected_direction_publication_errors(
+        data, project_root, manifest
+    )
     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)
-    if errors:
+    if errors or direction_errors:
         raise ReportAssemblyError(
             tuple(
                 AssemblyIssue(
@@ -574,5 +857,12 @@ def assemble_report(
                 )
                 for error in errors
             )
+            + tuple(
+                AssemblyIssue(
+                    "report-writer", str(target), "implementationPlanning", error
+                )
+                for error in direction_errors
+            )
         )
+    _materialize_planning_requests(target)
     return data

package/runtime/python/okstra_ctl/report_contract.py

@@ -149,7 +149,37 @@ IMPLEMENTATION_PLANNING_INVALIDATED_REQUIRED_HUMAN_FIELDS = (
 )
 
 
+def _renders_no_row(data: dict, field: str) -> bool:
+    """행 하나마다 찍히는 마커인데 행이 0개인가.
+
+    `<prop>.<array>.<subfield>` 꼴 필수 필드의 마커는 HTML 템플릿의 행 루프
+    안에 있다. 배열이 비면 마커는 나올 수 없고, 그래도 요구하면 렌더러가
+    만들 수 없는 것을 검증기가 요구한다. 실제로
+    `implementationOptionSelection.rankedOptions.requirementCoverage` 가 유효
+    후보 0건인 run 을 contract-violated 로 만들었다 — 스키마는 빈 배열을
+    허용하고, `implementation_options._validate_option_count_and_routing` 는
+    그 상태에서 `routing: blocked` 를 **요구**한다.
+
+    부모가 객체인 세 마디 필드(`decisionContext.originalRequirementIds`)는
+    행 단위가 아니므로 그대로 남는다.
+    """
+    parts = field.split(".")
+    if len(parts) < 3:
+        return False
+    node: object = data
+    for part in parts[:-1]:
+        if not isinstance(node, dict):
+            return False
+        node = node.get(part)
+    return isinstance(node, list) and not node
+
+
 def required_human_fields_for_report(task_type: str, data: dict) -> tuple[str, ...]:
+    fields = _required_human_fields_by_branch(task_type, data)
+    return tuple(field for field in fields if not _renders_no_row(data, field))
+
+
+def _required_human_fields_by_branch(task_type: str, data: dict) -> tuple[str, ...]:
     if task_type != "implementation-planning":
         return TASK_TYPE_REQUIRED_HUMAN_FIELDS.get(task_type, ())
     planning = data.get("implementationPlanning", {})
@@ -160,13 +190,6 @@ def required_human_fields_for_report(task_type: str, data: dict) -> tuple[str, .
     return IMPLEMENTATION_PLANNING_PLAN_READY_REQUIRED_HUMAN_FIELDS
 
 
-def report_property_for(task_type: str) -> str:
-    try:
-        return TASK_TYPE_DATA_PROPERTY[task_type]
-    except KeyError as exc:
-        raise ValueError(f"unsupported public report task type: {task_type}") from exc
-
-
 def html_template_for(task_type: str) -> str:
     try:
         return TASK_TYPE_HTML_TEMPLATE[task_type]