okstra 0.189.3 → 0.190.0

package/runtime/python/okstra_ctl/error_log_write.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import datetime as dt
 import json
+import re
 import os
 from pathlib import Path
 
@@ -186,6 +187,37 @@ def append_jsonl_line(path, record):
         os.close(fd)
 
 
+_LEAD_PHASE_LABEL = re.compile(r"^(?:phase-)?\d+(?:\.\d+)?$")
+
+
+def task_type_from_errors_log_path(out_path) -> str | None:
+    """`…/runs/<task-type>[/stage-N]/logs/errors-*.jsonl` 에서 task type 을 읽는다."""
+    parts = Path(str(out_path)).parts
+    if "runs" not in parts:
+        return None
+    index = parts.index("runs")
+    return parts[index + 1] if index + 1 < len(parts) else None
+
+
+def normalize_phase_label(phase, out_path) -> tuple[str | None, str | None]:
+    """``(phase, leadPhase)`` — 원장의 `phase` 는 task type 어휘 하나로 통일한다.
+
+    리드 계약은 자기 내부 단계 번호(`--phase 5.5` = 수렴 라운드)를 쓰고 워커는
+    task type 이름을 쓰므로, 한 run 의 errors.jsonl 에 `final-verification`·`5`·
+    `5.5` 가 섞였고 `prior-run-errors.md` 의 표가 그대로 그 셋을 나열했다(실측
+    2026-09-06, fontsninja-v3-site dev-10626). 숫자 라벨은 `leadPhase` 로 보존하고
+    `phase` 는 로그 경로가 말하는 task type 으로 적는다. 경로에서 읽을 수 없으면
+    라벨을 그대로 둔다 — 지어내지 않는다.
+    """
+    if phase is None:
+        return None, None
+    raw = str(phase)
+    if not _LEAD_PHASE_LABEL.match(raw):
+        return raw, None
+    task_type = task_type_from_errors_log_path(out_path)
+    return (task_type or raw), raw
+
+
 def append_observed(
     *,
     out_path,
@@ -216,11 +248,12 @@ def append_observed(
     # log: a written-then-flagged record is still a record someone can cite.
     context = normalize_cause_context(context, message=message)
     ts = _iso(now or _now_utc())
+    phase_value, lead_phase = normalize_phase_label(phase, out_path)
     rec = {
         "ts": ts,
         "recordedAt": ts,
         "taskKey": task_key,
-        "phase": str(phase),
+        "phase": phase_value,
         "agent": agent,
         "agentRole": agent_role,
         "model": model,
@@ -234,6 +267,8 @@ def append_observed(
         "stderrExcerpt": truncate_stderr(stderr_excerpt),
         "context": context,
     }
+    if lead_phase is not None:
+        rec["leadPhase"] = lead_phase
     from okstra_ctl.execution_identity import stored_identity
 
     rec.update(stored_identity(identity))
@@ -241,14 +276,17 @@ def append_observed(
     return rec
 
 
-def _worker_sidecar_record(entry, *, recorded_at, task_key, agent, agent_role, model, identity):
+def _worker_sidecar_record(
+    entry, *, recorded_at, task_key, agent, agent_role, model, identity, out_path=None,
+):
     error_type = entry.get("errorType")
     if error_type not in ALLOWED_ERROR_TYPES:
         raise ValueError(f"invalid errorType in sidecar: {error_type!r}")
+    phase_value, lead_phase = normalize_phase_label(entry.get("phase"), out_path)
     rec = {
         "ts": entry.get("ts"), "recordedAt": recorded_at,
         "taskKey": task_key,
-        "phase": str(entry.get("phase")) if entry.get("phase") is not None else None,
+        "phase": phase_value,
         "agent": agent, "agentRole": agent_role, "model": model,
         "source": "worker-reported", "errorType": error_type,
         "command": entry.get("command"), "commandKind": entry.get("commandKind"),
@@ -259,6 +297,8 @@ def _worker_sidecar_record(entry, *, recorded_at, task_key, agent, agent_role, m
             entry.get("context"), message=entry.get("message")
         ),
     }
+    if lead_phase is not None:
+        rec["leadPhase"] = lead_phase
     from okstra_ctl.execution_identity import stored_identity
 
     rec.update(stored_identity(identity))
@@ -315,7 +355,7 @@ def dump_from_worker_sidecar(
     for entry in payload.get("errors") or []:
         rec = _worker_sidecar_record(
             entry, recorded_at=recorded_at, task_key=task_key, agent=agent,
-            agent_role=agent_role, model=model, identity=identity,
+            agent_role=agent_role, model=model, identity=identity, out_path=out_path,
         )
         append_jsonl_line(out_path, rec)
         count += 1

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -10,6 +10,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from .worktree.cleanliness import nested_worktree_excludes
 from .write_policy import WritePolicy
 
 
@@ -95,17 +96,27 @@ class MutationAuditResult:
     before_digest: str
     after_digest: str
     git_projection: Mapping[str, Any]
+    # artifact root(프로젝트 루트)에 새로 생긴 비추적 파일 중 `.okstra/` 밖의 것.
+    # 워커의 도구가 남긴 로그·캐시라 위반이 아니라 기록이다 — 실측(2026-09-06,
+    # `fontsninja-v3-site` final-verification 001): 검증자의 브라우저 도구가
+    # `.playwright-mcp/*.log` 2건을 프로젝트 루트에 남겼고, 그 둘로 26KB 결과가
+    # `contract-failed-unattributed` 로 폐기됐다. 도구 사용 자체의 규칙 위반은
+    # 에러 원장(contract-violation)이 따로 잡는다.
+    untracked_artifact_paths: tuple[str, ...] = ()
+    warnings: tuple[str, ...] = ()
 
     def change_summary(self) -> dict[str, Any]:
         return {
             "mutationStatus": self.status,
             "changedPaths": list(self.changed_paths),
             "untrackedPaths": list(self.untracked_paths),
+            "untrackedArtifactPaths": list(self.untracked_artifact_paths),
             "sourceChanged": self.source_changed,
             "gitChanged": self.git_changed,
             "attribution": self.attribution,
             "retryAllowed": self.retry_allowed,
             "violations": list(self.violations),
+            "warnings": list(self.warnings),
             "beforeDigest": self.before_digest,
             "afterDigest": self.after_digest,
         }
@@ -123,12 +134,12 @@ class ExecutionMutationAudit:
         rows = tuple(policies)
         root, artifact_root = _validate_batch(rows)
         generated = _generated_paths(rows)
-        file_digests = _content_snapshot(root, generated | _ignored_paths(root))
+        file_digests = _content_snapshot(root, generated | _non_source_paths(root))
         artifact_digests = (
             file_digests
             if artifact_root == root
             else _content_snapshot(
-                artifact_root, generated | _ignored_paths(artifact_root)
+                artifact_root, generated | _non_source_paths(artifact_root)
             )
         )
         scratch_digests = _scratch_snapshot(rows)
@@ -195,9 +206,10 @@ class ExecutionMutationAudit:
             source_changes,
             out_of_plan_edits,
         )
-        violations.extend(
-            _artifact_policy_failures(before, rows, artifact_changed)
+        artifact_failures, untracked_artifact_changes = _artifact_policy_failures(
+            before, rows, artifact_changed
         )
+        violations.extend(artifact_failures)
         status = _terminal_status(
             rows,
             source_changed=bool(source_changes),
@@ -221,9 +233,23 @@ class ExecutionMutationAudit:
             before_digest=before.digest,
             after_digest=after.digest,
             git_projection=after.git_projection,
+            untracked_artifact_paths=tuple(sorted(untracked_artifact_changes)),
+            warnings=_audit_warnings(untracked_artifact_changes),
         )
 
 
+def _audit_warnings(untracked_artifact_changes: set[str]) -> tuple[str, ...]:
+    if not untracked_artifact_changes:
+        return ()
+    shown = sorted(untracked_artifact_changes)[:5]
+    more = len(untracked_artifact_changes) - len(shown)
+    tail = f" (+{more} more)" if more else ""
+    return (
+        "worker left untracked files in the artifact root outside `.okstra`: "
+        + ", ".join(shown) + tail,
+    )
+
+
 def _validate_batch(policies: tuple[WritePolicy, ...]) -> tuple[Path, Path]:
     if not policies:
         raise MutationAuditError("mutation audit requires at least one policy")
@@ -280,6 +306,11 @@ file failed both acceptance verifiers of an otherwise clean stage.
 
 One ecosystem, because one is what has been observed. A second name belongs here
 when a run produces the same evidence for it, not before.
+
+Tool logs that land in the *artifact root* (e.g. `.playwright-mcp/`) are not
+listed here either: `_artifact_policy_failures` records untracked files outside
+`.okstra/` instead of failing on them (observed 2026-09-06, `fontsninja-v3-site`
+final-verification 001).
 """
 
 
@@ -344,6 +375,30 @@ def _excluded(path: Path, excluded: frozenset[str]) -> bool:
     return any(relative == item or relative.startswith(item + "/") for item in excluded)
 
 
+def _non_source_paths(root: Path) -> frozenset[str]:
+    """감사에서 뺄 경로 — 레포가 무시하는 경로와 이 트리 안에 등록된 다른 worktree."""
+    return _ignored_paths(root) | _nested_worktree_paths(root)
+
+
+def _nested_worktree_paths(root: Path) -> frozenset[str]:
+    """`root` 아래에 git 이 등록한 다른 worktree 의 상대 경로.
+
+    형제 배치 이전의 implementation stage worktree 는 task worktree 안
+    (`<task>/stage-<N>/`)에 만들어졌고 final-verification 은 판정 뒤까지 그것을
+    남긴다. 중첩 트리는
+    이 워커의 소스가 아니라 다른 브랜치의 체크아웃이므로, 그 안에서 일어난
+    일(빌드 산출물, 다른 run 의 커밋)은 이 워커의 변경이 아니다. 실측
+    (2026-09-06, `fontsninja-v3-site` final-verification 001): 두 검증자의
+    attempt 가 `stage-1/.next/**` 107·109 경로를 `untrackedPaths` 로 실었다.
+    `nested_worktree_excludes` 가 okstra 의 clean 게이트에 쓰는 것과 같은
+    답(`git worktree list`)을 여기서도 쓴다 — 패턴을 따로 들고 있으면 둘이
+    갈린다.
+    """
+    return frozenset(
+        Path(entry).as_posix() for entry in nested_worktree_excludes(root)
+    )
+
+
 def _ignored_paths(root: Path) -> frozenset[str]:
     """레포가 스스로 소스가 아니라고 선언한 경로.
 
@@ -536,11 +591,22 @@ def _source_changes(
     }
 
 
+_OKSTRA_ARTIFACT_SUBTREE = ".okstra"
+
+
 def _artifact_policy_failures(
     snapshot: MutationSnapshot,
     policies: Sequence[WritePolicy],
     changed: set[str],
-) -> list[str]:
+) -> tuple[list[str], set[str]]:
+    """``(위반 목록, 위반이 아닌 비추적 신규 경로)``.
+
+    artifact root 의 변경 중 위반으로 남는 것은 두 부류다 — okstra 산출물
+    서브트리(`.okstra/`) 안의 허용 밖 쓰기와, git 이 추적하는 파일의 변경.
+    그 밖의 비추적 신규 파일은 워커의 도구가 남긴 로그·캐시이므로 소스 root 의
+    `_split_tracked` 와 같은 이유로 기록만 한다. artifact root 가 git 레포가
+    아니면 추적 여부를 알 수 없으므로 종전대로 전부 위반으로 본다.
+    """
     allowed = _allowed_artifact_paths(policies)
     orchestrator = {
         Path(value).relative_to(snapshot.artifact_root).as_posix()
@@ -553,8 +619,19 @@ def _artifact_policy_failures(
         and not any(_is_within(path, item) for item in orchestrator)
     }
     if snapshot.artifact_root == snapshot.root:
-        return []
-    return ["artifact-root change exceeds batch policy union"] if unauthorized else []
+        return [], set()
+    tracked = _tracked_paths(snapshot.artifact_root)
+    if tracked is None:
+        untracked_outside: set[str] = set()
+    else:
+        untracked_outside = {
+            path for path in unauthorized
+            if path not in tracked
+            and not _is_within(path, _OKSTRA_ARTIFACT_SUBTREE)
+        }
+    violating = unauthorized - untracked_outside
+    failures = ["artifact-root change exceeds batch policy union"] if violating else []
+    return failures, untracked_outside
 
 
 def _allowed_artifact_paths(policies: Sequence[WritePolicy]) -> set[str]:

package/runtime/python/okstra_ctl/fixed_text.py

@@ -4,16 +4,34 @@ from __future__ import annotations
 import re
 
 
+_CONTROL = re.compile(r"[\x00-\x09\x0b\x0c\x0e-\x1f\x7f-\x9f\u2028\u2029]")
+
+
+def _one_line(text: str) -> str:
+    """줄바꿈은 공백으로, 나머지 제어 문자는 `\\uXXXX` 로 바꿔 한 줄로 만든다."""
+    text = text.replace("\n", " ").replace("\r", " ")
+    return _CONTROL.sub(lambda match: f"\\u{ord(match.group(0)):04X}", text)
+
+
 def scalar(value: object) -> str:
-    """복합 값과 Markdown 줄 삽입을 노출하지 않는 scalar 문자열이다."""
+    """복합 값과 Markdown 줄 삽입을 노출하지 않는 scalar 문자열이다.
+
+    `line` 이 이 값을 인라인 코드 span(백틱 한 쌍) 안에 넣으므로 값 안의 백틱은
+    이스케이프한다. 백틱이 표기 그대로 남아야 하는 본문에는 `block` 을 쓴다.
+    """
     if value is None or value == "" or not isinstance(value, (str, int, float, bool)):
         return "-"
-    text = str(value).replace("`", "\\`").replace("\n", " ").replace("\r", " ")
-    return re.sub(
-        r"[\x00-\x09\x0b\x0c\x0e-\x1f\x7f-\x9f\u2028\u2029]",
-        lambda match: f"\\u{ord(match.group(0)):04X}",
-        text,
-    )
+    return _one_line(str(value).replace("`", "\\`"))
+
+
+def block(text: str) -> str:
+    """코드 span 밖에 놓이는 본문 한 덩어리의 투영이다.
+
+    백틱은 그대로 둔다 — 본문의 백틱은 코드 표기이고, 이스케이프하면 번역자가 그
+    백슬래시를 그대로 옮겨 렌더링에 남는다. 줄바꿈과 제어 문자 처리는 `scalar`
+    와 같아서 본문이 다음 헤딩을 위조할 수 없다.
+    """
+    return _one_line(text)
 
 
 def line(label: str, value: object) -> str: