okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/report_narrative.py

@@ -38,8 +38,25 @@ class _Node:
         self.children: list[_Node] = []
 
 
+_NARRATIVE_SCHEMA_RELATIVE = ("schemas", "report-narrative-v3.0.schema.json")
+
+
 def _narrative_schema_path() -> Path:
-    return Path(__file__).resolve().parents[2] / "schemas" / "report-narrative-v3.0.schema.json"
+    """schemas 를 실제로 가진 루트에서 해소한다.
+
+    부모 개수를 세면 체크아웃에서만 맞는다 — 설치본은 패키지가
+    `~/.okstra/lib/python/` 이고 schemas 는 `~/.okstra/schemas/` 라 한 단계
+    어긋나서, 설치본으로 실행할 때 서사 파싱이 스키마 없음으로 죽었다.
+    """
+    from .paths import find_asset_root
+
+    root = find_asset_root(_NARRATIVE_SCHEMA_RELATIVE)
+    if root is None:
+        raise NarrativeContractError(
+            "could not locate report-narrative-v3.0.schema.json. Set OKSTRA_HOME "
+            "or run from a checkout that contains schemas/."
+        )
+    return root.joinpath(*_NARRATIVE_SCHEMA_RELATIVE)
 
 
 def _narrative_schema() -> dict[str, Any]:
@@ -50,6 +67,77 @@ def _allowed_top_level() -> frozenset[str]:
     return frozenset(_narrative_schema().get("properties", {}))
 
 
+def allowed_top_level_fields() -> frozenset[str]:
+    """작성자가 최상위에 쓸 수 있는 필드 이름(서사 스키마의 properties)."""
+    return _allowed_top_level()
+
+
+# 완성 리포트 스키마가 작성자 소유 블록 안에서 required 로 거는 기계 소유 필드.
+# `writer_owned_data` 가 떼어내고 `_NESTED_FORBIDDEN` 이 저작을 막는 바로 그
+# 이름들이라, 값 제약을 그대로 쓰면 정상 서사가 전부 "필수 필드 없음" 으로
+# 깨진다. 앞의 둘은 `_NESTED_FORBIDDEN` 에서 파생시켜 두 목록이 갈라지지
+# 않게 한다.
+_MACHINE_OWNED_NESTED = frozenset(
+    {path.rsplit(".", 1)[-1] for path in _NESTED_FORBIDDEN} | {"designSurfaceCoverage"}
+)
+
+
+def _without_machine_owned_required(node: Any, *, negated: bool = False) -> Any:
+    """`required` 목록에서 기계 소유 필드 이름만 뺀 스키마 사본.
+
+    `not` 아래는 건드리지 않는다. 거기서 `required: [designPreparation]` 은
+    "이 필드가 있으면 안 된다" 는 뜻이고 서사에는 원래 없으니 이미 만족한다.
+    이름을 빼면 `not: {required: []}` 가 되는데, 빈 `required` 는 모든 객체가
+    만족하므로 그 `not` 은 항상 거짓이 된다 — 통과해야 할 분기를 통과 불가로
+    뒤집는다. 실제로 `direction-invalidated` 계획 분기가 그렇게 죽었다.
+    """
+    if isinstance(node, list):
+        return [_without_machine_owned_required(item, negated=negated) for item in node]
+    if not isinstance(node, dict):
+        return node
+    result: dict[str, Any] = {}
+    for key, value in node.items():
+        if key == "required" and isinstance(value, list) and not negated:
+            result[key] = [
+                name for name in value if name not in _MACHINE_OWNED_NESTED
+            ]
+        else:
+            result[key] = _without_machine_owned_required(
+                value, negated=negated or key == "not"
+            )
+    return result
+
+
+def _writer_owned_schema(schema: Mapping[str, Any]) -> dict[str, Any]:
+    """작성자가 쓴 서사에 걸 값 제약 — 완성 리포트 스키마에서 잘라 온다.
+
+    `report-narrative-v3.0.schema.json` 은 최상위 **이름** 허용목록이고 값은
+    전부 `{"type": "object"}` 스텁이다. 그 스텁으로만 검증하면 enum 밖 값과
+    빠진 필수 필드가 서사 단계를 통과하고, Phase 7 조립이 완성 리포트 스키마에
+    부딪힐 때에야 거절된다 — 작성기 워커가 이미 끝난 뒤라 되돌릴 방법이 없다.
+    실측(2026-08-26, stage 10 run 002): `verdictCard.direction` 에 enum 에 없는
+    `proceed` 가, `humanSummary` 에 필수 `whyItMatters` 가 빠진 채로 서사가
+    통과했고 `report-finalize` 의 `project-activity` 가 exit 1 로 떨어졌다.
+
+    그래서 이름 소유권은 서사 스키마에서, 값 제약은 넘겨받은 완성 리포트
+    스키마에서 가져온다. 두 벌을 만들지 않으므로 드리프트가 생기지 않는다.
+    서사는 부분 문서다 — 최상위 `required` 는 싣지 않는다. 이 run 의 task
+    블록만 있고 나머지 task-type 블록과 기계 소유 최상위 필드는 없기 때문이다.
+    """
+    allowed = _allowed_top_level()
+    properties = {
+        key: value
+        for key, value in schema.get("properties", {}).items()
+        if key in allowed
+    }
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": _without_machine_owned_required(properties),
+        "$defs": _without_machine_owned_required(schema.get("$defs", {})),
+    }
+
+
 def writer_owned_data(data: Mapping[str, Any]) -> dict[str, Any]:
     """완성 리포트에서 보고서 작성자 소유 필드만 복사한다."""
     owned = {
@@ -190,7 +278,7 @@ def _parse_tree(markdown: str) -> _Node:
             _append_node(stack, field, item, level, number)
         elif value:
             level = _line_level(value.group("indent"), number)
-            _append_value(stack, value.group("value"), level, number)
+            _append_value(stack, value.group("value"), level, number, lines)
         else:
             raise NarrativeContractError(
                 f"line {number}: unsupported Markdown syntax `{line.strip()}` — "
@@ -216,9 +304,45 @@ def _append_node(stack: list[_Node], field: Any, item: Any, level: int, number:
     stack.append(node)
 
 
-def _append_value(stack: list[_Node], value: str, level: int, number: int) -> None:
+def _misplaced_value_lines(lines: list[str]) -> int:
+    """자기 라벨보다 두 칸 더 들여쓰지 않은 `> value` 줄의 수.
+
+    파서는 첫 결함에서 멈추므로 규모를 말하지 못한다 — 129줄이 전부 0열에
+    붙은 서술문이 `line 5` 한 건으로 보고됐다(2026-09-02 실측). 여기서는
+    직전 라벨(`- **…**` / `- Item N`)의 들여쓰기와 견줘 세기만 한다; 판정은
+    여전히 파서의 것이다.
+    """
+    misplaced = 0
+    label_indent = None
+    for line in lines[1:]:
+        if not line.strip():
+            continue
+        match = _FIELD_RE.match(line) or _ITEM_RE.match(line)
+        if match:
+            label_indent = len(match.group("indent"))
+            continue
+        value = _VALUE_RE.match(line)
+        if value and label_indent is not None:
+            if len(value.group("indent")) != label_indent + 2:
+                misplaced += 1
+    return misplaced
+
+
+def _append_value(
+    stack: list[_Node], value: str, level: int, number: int, lines: list[str] | None = None,
+) -> None:
     if stack[-1].level != level - 1:
-        raise NarrativeContractError(f"line {number}: value is outside its field")
+        count = _misplaced_value_lines(lines) if lines is not None else 0
+        scale = (
+            f"; {count} value line(s) in this file share the defect"
+            if count > 1
+            else ""
+        )
+        raise NarrativeContractError(
+            f"line {number}: value is outside its field — a `> value` line is "
+            "indented exactly two spaces deeper than the `- **Label**` or "
+            f"`- Item N` line it belongs to{scale}"
+        )
     if stack[-1].children:
         raise NarrativeContractError(f"line {number}: field mixes values and children")
     stack[-1].values.append(value)
@@ -234,7 +358,37 @@ def _allowed_labels(node: Any, index: SchemaIndex, path: str) -> list[str]:
     return sorted(humanise(key) for key in keys)
 
 
-def _field_key(label: str, node: Any, index: SchemaIndex, path: str) -> str:
+class _Defects:
+    """값 단계에서 모은 결함. 첫 건에서 멈추지 않고 문서 전체를 읽는다.
+
+    파서가 첫 강제 변환 실패에서 예외를 내던 동안, 같은 종류의 결함이 여러
+    자리에 있어도 한 자리만 보고돼 작성자가 같은 문서를 회차마다 한 자리씩
+    고쳤다(2026-09-03 실측, dev-10626 implementation-option-selection: 소수
+    `coveragePercent` 가 랭킹 옵션 둘에 있는데 `rankedOptions[1]` 한 건만).
+    스키마 검증(`validate`)은 이미 전건을 모으므로 값 단계도 그렇게 한다.
+    """
+
+    def __init__(self) -> None:
+        self.messages: list[str] = []
+        self.paths: list[str] = []
+
+    def add(self, path: str, message: str) -> None:
+        self.paths.append(path)
+        self.messages.append(message)
+
+    def covers(self, error: str) -> bool:
+        """스키마 검증이 같은 자리(또는 그 아래)에 낸 오류인가 — 값 단계가 이미
+        보고한 자리를 두 번 말하지 않는다."""
+        location = error.split(": ", 1)[0]
+        return any(
+            location == path or location.startswith(f"{path}.") or location.startswith(f"{path}[")
+            for path in self.paths
+        )
+
+
+def _field_key(
+    label: str, node: Any, index: SchemaIndex, path: str, defects: _Defects,
+) -> str | None:
     candidates: dict[str, list[str]] = {}
     for key in index.key_order(node):
         candidates.setdefault(label_key(humanise(key)), []).append(key)
@@ -247,20 +401,26 @@ def _field_key(label: str, node: Any, index: SchemaIndex, path: str) -> str:
     if not matches:
         allowed = _allowed_labels(node, index, path)
         listing = ", ".join(f"`{item}`" for item in allowed) or "(none)"
-        raise NarrativeContractError(
+        defects.add(
+            display_path,
             f"owner=report-writer field `{display_path}` is not an allowed unique "
-            f"field; allowed at this position: {listing}"
+            f"field; allowed at this position: {listing}",
         )
+        return None
     if len(matches) > 1:
         collisions = ", ".join(f"`{key}`" for key in matches)
-        raise NarrativeContractError(
+        defects.add(
+            display_path,
             f"owner=report-writer field `{display_path}` is not an allowed unique "
-            f"field; the label matches more than one schema key: {collisions}"
+            f"field; the label matches more than one schema key: {collisions}",
         )
+        return None
     return matches[0]
 
 
-def _parse_scalar(values: list[str], node: Any, index: SchemaIndex, path: str) -> Any:
+def _parse_scalar(
+    values: list[str], node: Any, index: SchemaIndex, path: str, defects: _Defects,
+) -> Any:
     types = _node_types(node, index)
     text = "\n".join(values)
     if text == EMPTY_MARKER and "null" in types:
@@ -270,17 +430,21 @@ def _parse_scalar(values: list[str], node: Any, index: SchemaIndex, path: str) -
     if "integer" in types:
         try:
             return int(text)
-        except ValueError as exc:
-            raise NarrativeContractError(f"{path}: expected integer") from exc
+        except ValueError:
+            defects.add(path, f"{path}: expected integer")
+            return text
     if "number" in types:
         try:
             return float(text)
-        except ValueError as exc:
-            raise NarrativeContractError(f"{path}: expected number") from exc
+        except ValueError:
+            defects.add(path, f"{path}: expected number")
+            return text
     return text
 
 
-def _parse_value(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -> Any:
+def _parse_value(
+    node: _Node, schema_node: Any, index: SchemaIndex, path: str, defects: _Defects,
+) -> Any:
     types = _node_types(schema_node, index)
     if node.values:
         if node.values == [EMPTY_MARKER] and "null" in types:
@@ -289,52 +453,70 @@ def _parse_value(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -
             return {}
         if node.values == [EMPTY_MARKER] and "array" in types:
             return []
-        return _parse_scalar(node.values, schema_node, index, path)
+        return _parse_scalar(node.values, schema_node, index, path, defects)
     if "array" in types or all(child.kind == "item" for child in node.children):
-        return _parse_array(node, schema_node, index, path)
-    return _parse_object(node, schema_node, index, path)
+        return _parse_array(node, schema_node, index, path, defects)
+    return _parse_object(node, schema_node, index, path, defects)
 
 
-def _parse_array(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -> list[Any]:
+def _parse_array(
+    node: _Node, schema_node: Any, index: SchemaIndex, path: str, defects: _Defects,
+) -> list[Any]:
     if any(child.kind != "item" for child in node.children):
-        raise NarrativeContractError(f"{path}: array requires Item rows")
+        defects.add(path, f"{path}: array requires Item rows")
+        return []
     positions = [int(child.label) for child in node.children]
     if positions != list(range(1, len(positions) + 1)):
-        raise NarrativeContractError(f"{path}: Item numbers must be 1..N")
+        defects.add(path, f"{path}: Item numbers must be 1..N")
+        return []
     item_schema = index.item(schema_node)
     return [
-        _parse_value(child, item_schema, index, f"{path}[{position - 1}]")
+        _parse_value(child, item_schema, index, f"{path}[{position - 1}]", defects)
         for position, child in zip(positions, node.children, strict=True)
     ]
 
 
-def _parse_object(node: _Node, schema_node: Any, index: SchemaIndex, path: str) -> dict[str, Any]:
+def _parse_object(
+    node: _Node, schema_node: Any, index: SchemaIndex, path: str, defects: _Defects,
+) -> dict[str, Any]:
     result: dict[str, Any] = {}
     for child in node.children:
         if child.kind != "field":
-            raise NarrativeContractError(f"{path}: object requires named fields")
-        key = _field_key(child.label, schema_node, index, path)
+            defects.add(path, f"{path}: object requires named fields")
+            return result
+        key = _field_key(child.label, schema_node, index, path, defects)
+        if key is None:
+            continue
         child_path = f"{path}.{key}" if path else key
         if child_path in _NESTED_FORBIDDEN:
-            raise NarrativeContractError(
-                f"owner=report-writer cannot author `{path}.{child.label}`"
+            defects.add(
+                child_path, f"owner=report-writer cannot author `{path}.{child.label}`"
             )
+            continue
         if key in result:
-            raise NarrativeContractError(f"duplicate field: {child_path}")
+            defects.add(child_path, f"duplicate field: {child_path}")
+            continue
         child_schema = index.child(schema_node, key)
         if not _node_types(child_schema, index):
             child_schema = index.schema_for_key(key)
         result[key] = _parse_value(
-            child, child_schema, index, child_path
+            child, child_schema, index, child_path, defects
         )
     return result
 
 
 def parse_narrative(markdown: str, schema: Mapping[str, Any]) -> dict[str, Any]:
-    """Markdown을 작성자 소유 자료로 읽고 소유권 표면을 검증한다."""
+    """Markdown을 작성자 소유 자료로 읽고, 소유권 표면과 값 제약을 검증한다.
+
+    `schema` 는 완성 리포트 스키마다. 이름·타입 해석과 값 검증이 모두 그
+    한 벌에서 나온다(`_writer_owned_schema`). 값 단계의 결함(강제 변환·모양·
+    허용되지 않는 필드)과 스키마 검증의 결함을 한 예외에 모두 싣는다 — 값
+    단계가 보고한 자리는 스키마 검증에서 다시 말하지 않는다.
+    """
     root = _parse_tree(markdown)
     index = SchemaIndex(schema)
-    result = _parse_object(root, schema, index, "")
+    defects = _Defects()
+    result = _parse_object(root, schema, index, "", defects)
     unknown = sorted(set(result) - _allowed_top_level())
     if unknown:
         labels = [humanise(key) for key in unknown]
@@ -345,7 +527,11 @@ def parse_narrative(markdown: str, schema: Mapping[str, Any]) -> dict[str, Any]:
             f"owner=report-writer cannot author fields: {labels}; "
             f"writer-owned top-level fields: {owned}"
         )
-    errors = validate(result, _narrative_schema())
-    if errors:
-        raise NarrativeContractError("; ".join(errors))
+    errors = [
+        error
+        for error in validate(result, _writer_owned_schema(schema))
+        if not defects.covers(error)
+    ]
+    if defects.messages or errors:
+        raise NarrativeContractError("; ".join(defects.messages + errors))
     return result

package/runtime/python/okstra_ctl/report_projections.py

@@ -168,6 +168,9 @@ def _worker_details(team_state: Mapping[str, Any]) -> list[dict[str, Any]]:
         usage = worker.get("usage") if isinstance(worker.get("usage"), Mapping) else {}
         row = {"label": _text(worker.get("role") or worker.get("workerId"), "Worker")}
         _populate_usage(row, usage)
+        # 작업 시간은 executionStatus 칸이다. workerDetails 스키마는
+        # durationMs 를 허용하지 않아 조립이 additionalProperties 로 거절한다.
+        row.pop("durationMs", None)
         for key in ("totalTokens", "cacheReadTokens", "billableTokens", "costUsd", "cliTotalTokens", "cliCostUsd"):
             row.setdefault(key, None)
         result.append(row)
@@ -231,6 +234,9 @@ def project_design(
 def _round_history(state: Mapping[str, Any]) -> dict[str, Any]:
     if not (state.get("config") or {}).get("enabled", True):
         return {"disabled": True}
+    skip_reason = state.get("round2SkippedReason", "not-skipped")
+    if skip_reason == "auto-disabled":
+        skip_reason = "single-analyser-only"
     rows = []
     for row in state.get("roundHistory") or []:
         if not isinstance(row, Mapping):
@@ -243,7 +249,7 @@ def _round_history(state: Mapping[str, Any]) -> dict[str, Any]:
             "dispatches": json.dumps(row.get("dispatches") or [], ensure_ascii=False),
             "skippedWorkers": json.dumps(row.get("skippedWorkers") or [], ensure_ascii=False),
         })
-    return {"rounds": rows, "round2SkippedReason": state.get("round2SkippedReason", "not-skipped")}
+    return {"rounds": rows, "round2SkippedReason": skip_reason}
 
 
 def _source_items(finding: Mapping[str, Any]) -> list[str]:
@@ -265,7 +271,7 @@ def project_convergence(state: Mapping[str, Any]) -> dict[str, Any]:
         ticket_id = _text(ticket_ids[0] if ticket_ids else "unknown", "unknown")
         if finding.get("classification") in {"full-consensus", "partial-consensus"}:
             row = {
-                "id": f"C-{len(consensus) + 1:03d}",
+                "id": f"CV-{len(consensus) + 1:03d}",
                 "ticketId": ticket_id,
                 "statement": _text(finding.get("summary"), "Converged finding"),
                 "sourceItems": _source_items(finding),