okstra 0.158.1 → 0.160.0

package/runtime/python/okstra_ctl/error_report.py

@@ -35,6 +35,62 @@ def _md_table(header: list[str], rows: list[list[str]]) -> str:
     return "\n".join([line, sep, *body])
 
 
+# The two types a next run can actually act on: a worker that broke its
+# contract (adjust the roster or pre-check its result) and a tool that failed
+# (raise a budget, or expect the same failure). Everything else is either
+# already retried or not actionable at preparation time.
+CARRY_FORWARD_ERROR_TYPES = ("contract-violation", "tool-failure")
+
+
+def prior_run_error_digest(
+    task_root: Path, *, error_types: tuple[str, ...] = CARRY_FORWARD_ERROR_TYPES
+) -> str:
+    """Markdown digest of the traps this task's earlier runs already hit.
+
+    Read-only: unlike ``build_and_write`` this writes no report file, so it is
+    safe to call while a run is being prepared. The records have always been on
+    disk under ``runs/*/logs/errors-*.jsonl`` and ``okstra error-report`` has
+    aggregated them for just as long — what was missing is anyone reading them
+    *before* the next run, so the same violation recurred and the response was
+    improvised every time.
+
+    Returns ``""`` when nothing actionable is recorded, which is the signal for
+    the caller to stage no file at all rather than an empty one.
+    """
+    records, _ = parse_records(glob_error_logs(task_root))
+    carried = [
+        record
+        for record in records
+        if str(record.get("errorType", "")) in error_types
+    ]
+    if not carried:
+        return ""
+    counts: dict[tuple[str, str, str], int] = {}
+    for record in carried:
+        key = (
+            str(record.get("errorType", "")),
+            str(record.get("phase", "")),
+            str(record.get("agent", "")),
+        )
+        counts[key] = counts.get(key, 0) + 1
+    table = _md_table(
+        ["Error type", "Phase", "Agent", "Count"],
+        [
+            [error_type, phase or "—", agent or "—", str(count)]
+            for (error_type, phase, agent), count in sorted(
+                counts.items(), key=lambda item: (-item[1], item[0])
+            )
+        ],
+    )
+    return (
+        "# Prior-Run Errors\n\n"
+        "`contract-violation` and `tool-failure` records this task's earlier "
+        "runs wrote. These are not findings about the work — they are traps "
+        "that fired before and can fire again in this run.\n\n"
+        f"{table}\n"
+    )
+
+
 def render_markdown(*, task_key, records, agg, parse_skipped, generated_at) -> str:
     by_type = ", ".join(f"{k}: {v}" for k, v in sorted(agg["byErrorType"].items())) or "_없음_"
     by_src = ", ".join(f"{k}: {v}" for k, v in sorted(agg["bySource"].items())) or "_없음_"

package/runtime/python/okstra_ctl/error_zip.py

@@ -19,10 +19,16 @@ from okstra_ctl.locks import central_lock
 from okstra_ctl.paths import okstra_home, resolve_under_root
 
 
-def _run_dirs(home: Path) -> list[tuple[str, Path]]:
+def run_dirs(home: Path) -> list[tuple[str, Path, dict]]:
+    """글로벌 run-index 순회의 단일 참조점 — `(project_root, run_dir, row)`.
+
+    인덱스 행을 함께 돌려주는 이유: 행에는 `status` 처럼 디스크만 봐서는 알 수
+    없는 사실이 실려 있다(`run_index_row.build_run_index_row`). 행을 버리면 그게
+    필요한 소비자가 recent/active 순회를 통째로 복제하게 된다.
+    """
     rows = read_jsonl(home / "recent.jsonl") + read_jsonl(home / "active.jsonl")
     seen: set[tuple[str, str]] = set()
-    out: list[tuple[str, Path]] = []
+    out: list[tuple[str, Path, dict]] = []
     for row in rows:
         project_root = str(row.get("projectRoot", ""))
         run_dir_rel = str(row.get("runDirRel", ""))
@@ -32,7 +38,7 @@ def _run_dirs(home: Path) -> list[tuple[str, Path]]:
         seen.add(key)
         run_dir = resolve_under_root(project_root, run_dir_rel)
         if run_dir is not None:
-            out.append((project_root, run_dir))
+            out.append((project_root, run_dir, row))
     return out
 
 
@@ -48,7 +54,7 @@ def collect_records(home: Path) -> tuple[list[dict], dict]:
     project_roots: set[str] = set()
     reachable = 0
     unreachable = 0
-    for project_root, run_dir in _run_dirs(home):
+    for project_root, run_dir, _row in run_dirs(home):
         if not run_dir.exists():
             unreachable += 1
             continue
@@ -169,9 +175,12 @@ def anonymize(records: list[dict]) -> tuple[list[dict], dict]:
                 continue
             scrub = _scrub_freetext if k in _FREETEXT_FIELDS else _scrub
             item[k] = scrub(rec.get(k), token_map)
-        task_key = str(rec.get("taskKey", ""))
-        if ":" in task_key:
-            item["taskKey"] = token + task_key[task_key.index(":"):]
+        if "taskKey" in item:
+            # 프로젝트 접두만 토큰화하고 나머지를 남기면 타겟의 티켓 번호가
+            # 그대로 나간다 — `proj-2:DEV-9388:DEV-9428` 은 익명이 아니다.
+            # 클러스터를 식별하는 것은 이미 지문이므로, 태스크 아이디는 공개
+            # 이슈나 공유 zip 을 읽는 사람에게 아무것도 더 주지 않는다.
+            item["taskKey"] = token
         item["sourceProject"] = token
         clean.append(item)
     return clean, token_map
@@ -193,9 +202,13 @@ def cluster_key(rec: dict) -> str:
     ])
 
 
-def build_clusters(records: list[dict]) -> tuple[list[dict], list[str]]:
+def build_clusters(records: list[dict], *,
+                   project_field: str = "sourceProject") -> tuple[list[dict], list[str]]:
     """클러스터 목록과, records 와 같은 순서의 레코드별 cluster_key 를 함께 반환.
-    호출자가 직렬화 시 키를 재계산(정규식 중복)하지 않도록 키를 노출한다."""
+    호출자가 직렬화 시 키를 재계산(정규식 중복)하지 않도록 키를 노출한다.
+
+    project_field 는 확산을 세는 소스다. 익명화 레코드는 anonymize() 가 붙인
+    `sourceProject`, 원본 레코드는 collect_records() 가 붙인 `_projectRoot` 를 쓴다."""
     buckets: dict[str, dict] = {}
     keys: list[str] = []
     for rec in records:
@@ -207,7 +220,7 @@ def build_clusters(records: list[dict]) -> tuple[list[dict], list[str]]:
             "count": 0, "projects": set(), "sample": str(rec.get("message", "")),
         })
         b["count"] += 1
-        b["projects"].add(str(rec.get("sourceProject", "")))
+        b["projects"].add(str(rec.get(project_field, "")))
     clusters = []
     for b in buckets.values():
         b["projects"] = sorted(p for p in b["projects"] if p)

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -15,6 +15,7 @@ import sys
 from dataclasses import asdict, dataclass
 from pathlib import Path
 
+from okstra_ctl.final_report_paths import final_report_data_path
 from okstra_ctl.stage_citations import cited_stage_numbers
 from okstra_ctl.stage_targets import downstream_stage_closure
 
@@ -94,15 +95,37 @@ def _plan_item_stages(item: dict) -> set[int]:
     return cited_stage_numbers(str(item.get("subject") or ""))
 
 
-def _stages_blocked_on(coverage: object, clarification_id: str) -> set[int]:
+_BLOCK_MARKER_FIELDS = ("status", "approvalDisposition")
+
+
+def coverage_row_blocked_on(row: object, clarification_id: str) -> bool:
+    """Whether a requirement-coverage row records a block on this clarification.
+
+    The marker lives in either of two fields, and the schema says so: `status`
+    allows `blocked C-NNN`, and so does `approvalDisposition`. A row recorded
+    as a `documented-deviation` carries its block in the latter, so reading
+    `status` alone missed it — which forced the whole re-run to full for an
+    answer whose blast radius the report did record.
+
+    `validate-run.py` shares this predicate to require that every approval
+    blocker has at least one such link. One definition, so the gate cannot
+    demand a link shape this resolver would refuse to follow.
+    """
+    if not isinstance(row, dict):
+        return False
     blocked = f"blocked {clarification_id}"
+    return any(
+        str(row.get(field) or "").strip() == blocked
+        for field in _BLOCK_MARKER_FIELDS
+    )
+
+
+def _stages_blocked_on(coverage: object, clarification_id: str) -> set[int]:
+    """Stages of every coverage row blocked on ``clarification_id``."""
     stages: set[int] = set()
     for row in coverage if isinstance(coverage, list) else []:
-        if not isinstance(row, dict):
-            continue
-        if str(row.get("status") or "").strip() != blocked:
-            continue
-        stages |= cited_stage_numbers(str(row.get("coveredBy") or ""))
+        if coverage_row_blocked_on(row, clarification_id):
+            stages |= cited_stage_numbers(str(row.get("coveredBy") or ""))
     return stages
 
 
@@ -119,19 +142,9 @@ def clarification_impacted_stages(
     Raises when any id resolves to no stage — a partially-resolved set would
     narrow the re-run past an answer whose blast radius nobody established.
     """
-    planning = data.get("implementationPlanning")
-    if not isinstance(planning, dict):
-        raise ValueError("implementationPlanning is missing")
-    verification = planning.get("planBodyVerification")
-    plan_items = (verification or {}).get("planItems") if isinstance(verification, dict) else []
-    coverage = planning.get("requirementCoverage")
-
     impacted: set[int] = set()
     for clarification_id in sorted(clarification_ids):
-        stages = _stages_blocked_on(coverage, clarification_id)
-        for item in plan_items if isinstance(plan_items, list) else []:
-            if isinstance(item, dict) and item.get("clarificationId") == clarification_id:
-                stages |= _plan_item_stages(item)
+        stages = stages_for_clarification(data, clarification_id)
         if not stages:
             raise ValueError(
                 f"answered clarification {clarification_id} traces to no stage "
@@ -141,6 +154,97 @@ def clarification_impacted_stages(
     return impacted
 
 
+def stages_for_clarification(data: dict, clarification_id: str) -> set[int]:
+    """Stages the prior run linked to one clarification; empty when it linked none.
+
+    Separate from the raising walk above because the preview needs the same
+    lookup without the exception: it reports *which* ids are unlinked, and a
+    raise on the first one would hide the rest.
+    """
+    planning = data.get("implementationPlanning")
+    if not isinstance(planning, dict):
+        raise ValueError("implementationPlanning is missing")
+    verification = planning.get("planBodyVerification")
+    plan_items = (
+        verification.get("planItems") if isinstance(verification, dict) else []
+    )
+    stages = _stages_blocked_on(planning.get("requirementCoverage"), clarification_id)
+    for item in plan_items if isinstance(plan_items, list) else []:
+        if isinstance(item, dict) and item.get("clarificationId") == clarification_id:
+            stages |= _plan_item_stages(item)
+    return stages
+
+
+def preview_link_availability(data: dict, clarification_ids: set[str]) -> dict:
+    """Would the answered ids let the next re-run narrow — decided without a SHA.
+
+    The full decision also needs safety condition C1 (base ref unchanged), and
+    the current base SHA only exists once `render-bundle` has written a
+    manifest and registered the run. By then the two-hour cost of a full
+    re-verification is already committed. Link availability is the half that
+    decides the common case and needs nothing but the prior report, so it can
+    be shown while the run is still reshapeable.
+
+    `wouldForceFull: false` is therefore not a promise of `incremental` — it
+    says only that this half found nothing forcing full.
+    """
+    unlinked = sorted(
+        clarification_id
+        for clarification_id in clarification_ids
+        if not stages_for_clarification(data, clarification_id)
+    )
+    if unlinked:
+        return {
+            "wouldForceFull": True,
+            "unlinkedIds": unlinked,
+            "reason": (
+                f"{', '.join(unlinked)} trace(s) to no stage in the prior report — "
+                "an answer whose blast radius was never recorded cannot narrow anything"
+            ),
+        }
+    if not clarification_ids:
+        return {
+            "wouldForceFull": True,
+            "unlinkedIds": [],
+            "reason": "no answered clarifications given; nothing to narrow with",
+        }
+    return {
+        "wouldForceFull": False,
+        "unlinkedIds": [],
+        "reason": (
+            "every answered id traces to a stage; the base-ref comparison at run "
+            "time still decides the final mode"
+        ),
+    }
+
+
+def preview_link_availability_for_report(
+    report: Path, clarification_ids: set[str]
+) -> dict:
+    """`preview_link_availability` for a report on disk, data read included.
+
+    Both callers hold a report path, not a loaded dict. Leaving the read at
+    each call site is how they would drift on what a missing or unreadable
+    data sibling means — and that verdict is the one the user acts on.
+    """
+    data_path = final_report_data_path(report)
+    if not data_path.is_file():
+        return {
+            "wouldForceFull": True,
+            "unlinkedIds": [],
+            "reason": f"prior report has no data sibling at {data_path.name}",
+        }
+    try:
+        data = json.loads(data_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        return {
+            "wouldForceFull": True,
+            "unlinkedIds": [],
+            "reason": f"prior report data is unreadable: {exc}",
+        }
+    return preview_link_availability(data, clarification_ids)
+
+
 def decide_scope(
     *,
     stages: list[tuple[int, list[int]]],
@@ -168,11 +272,43 @@ def decide_scope(
     return IncrementalDecision("incremental", reverify, carry, f"closure {reverify} within cutoff")
 
 
+def _preview_result(args) -> dict:
+    """`preview_link_availability` over CLI args, degrading to full on bad input.
+
+    Same posture as the decision path below: a caller reads the answer off
+    stdout, so a traceback would leave it with nothing. `full` is the safe
+    answer when the input cannot be read.
+    """
+    try:
+        data = json.loads(Path(args.prev_data).read_text(encoding="utf-8"))
+        answered = {
+            token.strip()
+            for token in args.answered_clarifications.split(",")
+            if token.strip()
+        }
+        return preview_link_availability(data, answered)
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        return {
+            "wouldForceFull": True,
+            "unlinkedIds": [],
+            "reason": f"invalid incremental-scope input: {exc}",
+        }
+
+
 def main(argv: list[str]) -> int:
     ap = argparse.ArgumentParser(prog="okstra incremental-scope")
     ap.add_argument("--prev-data", required=True, help="prior run final-report data.json")
-    ap.add_argument("--cur-base-sha", required=True)
-    ap.add_argument("--prev-base-sha", required=True)
+    # Not required: `--preview` answers the link half before a worktree base
+    # commit exists, which is the whole reason that mode is there.
+    ap.add_argument("--cur-base-sha", default="")
+    ap.add_argument("--prev-base-sha", default="")
+    ap.add_argument(
+        "--preview",
+        action="store_true",
+        help="report whether the answered ids could narrow the re-run, using the "
+             "prior report alone. Side-effect free and needs no base SHA, so it "
+             "can run before the decision to start is irreversible",
+    )
     ap.add_argument("--impacted", default="", help="comma-separated impacted stage numbers")
     ap.add_argument("--prep-items", default="", help="comma-separated changed PREP item IDs")
     ap.add_argument(
@@ -190,6 +326,10 @@ def main(argv: list[str]) -> int:
     )
     args = ap.parse_args(argv)
 
+    if args.preview:
+        print(json.dumps(_preview_result(args), ensure_ascii=False))
+        return 0
+
     declared = args.full_reason.strip()
     if declared:
         # The lead's structural judgement is exactly what the back-trace cannot

package/runtime/python/okstra_ctl/initial_prompt_materialization.py

@@ -52,6 +52,14 @@ class InitialPromptMaterializationRequest:
     delivery_mode: PromptDeliveryMode
     workers: tuple[InitialPromptWorkerRequest, ...]
 
+    def __post_init__(self) -> None:
+        # A `str` in any of these surfaced as `'str' object has no attribute
+        # 'resolve'`, wrapped into `render_failed`, which named neither the
+        # field nor the caller. Coercing removes the failure rather than
+        # improving its message.
+        for field in ("project_root", "run_manifest_path", "runtime_root"):
+            object.__setattr__(self, field, Path(getattr(self, field)))
+
 
 class InitialPromptMaterializationError(RuntimeError):
     reason: MaterializationReason
@@ -63,7 +71,7 @@ class InitialPromptMaterializationError(RuntimeError):
 
 MaterializeInitialPrompts = Callable[
     [InitialPromptMaterializationRequest],
-    tuple[Path, ...],
+    dict[str, Path],
 ]
 
 _MATERIALIZABLE_AUDIENCES = frozenset({
@@ -124,8 +132,13 @@ class _PublishedPrompt:
 
 def materialize_initial_prompts(
     request: InitialPromptMaterializationRequest,
-) -> tuple[Path, ...]:
-    """Materialize selected initial prompts in request order."""
+) -> dict[str, Path]:
+    """Materialize the selected initial prompts, keyed by worker id.
+
+    A positional sequence made every caller re-pair prompts with workers by
+    index; a pairing that slips still type-checks and dispatches the wrong
+    prompt to the wrong worker.
+    """
     try:
         return _materialize_initial_prompts(request)
     except InitialPromptMaterializationError:
@@ -139,7 +152,7 @@ def materialize_initial_prompts(
 
 def _materialize_initial_prompts(
     request: InitialPromptMaterializationRequest,
-) -> tuple[Path, ...]:
+) -> dict[str, Path]:
     context = _load_materialization_context(request)
     resolved_items = [
         _resolve_prompt_item(context, worker)
@@ -157,7 +170,7 @@ def _materialize_initial_prompts(
         )
         _validate_published_set(context, published)
         completed = True
-        return tuple(prompt.path for prompt in published)
+        return {prompt.worker.worker_id: prompt.path for prompt in published}
     finally:
         cleanup_error = _remove_temp_files(items)
         if completed and cleanup_error is not None:

package/runtime/python/okstra_ctl/issue_signals.py

@@ -0,0 +1,186 @@
+"""이슈 판정 신호 — 원본(익명화 전) 레코드에서만 계산되는 순수 함수.
+
+익명화는 message/stderrExcerpt/command 의 경로를 <path> 로 붕괴시키므로
+(error_zip._PATHISH), 경로 기반 신호는 익명화 뒤에는 계산할 수 없다.
+신호 값 자체는 불리언·카운트라 공개 이슈에 실어도 안전하다.
+"""
+from __future__ import annotations
+
+OKSTRA_DEFECT = "okstra-defect"
+ENVIRONMENT_POLICY = "environment-policy"
+TARGET_CODE = "target-code"
+
+# okstra-defect 판정에 필요한 강한 지지 신호 수. 한 신호만으로는 공개 이슈를
+# 만들지 않는다.
+MIN_SUPPORTING_SIGNALS = 2
+
+# 단일 phase 클러스터면 무조건 켜지므로 판정을 지탱하지 못한다. 근거로 보고하되
+# 최소 근거 수에는 세지 않는다 — 세면 "근거 2개"가 "진짜 근거 1개 + 공짜 한 자리"가 된다.
+WEAK_SIGNALS = ("phaseLock",)
+
+# 리드가 규칙 위반을 관측한 지점에서 찍는 값이라(prompts/lead/okstra-lead-contract.md)
+# 워커 자기신고와 성격이 다르고, 그 자체로 okstra 배선 문제를 가리킨다. 확산이 없어도
+# — 한 프로젝트·한 태스크 안에서만 반복돼도 — 최소 근거 수를 우회한다.
+SELF_SUFFICIENT_SIGNALS = ("contractViolation",)
+
+SIGNAL_SUPPORT = {
+    "contractViolation": OKSTRA_DEFECT,
+    "okstraOwnedPath": OKSTRA_DEFECT,
+    "invariantViolated": OKSTRA_DEFECT,
+    "taskSpread": OKSTRA_DEFECT,
+    "projectSpread": OKSTRA_DEFECT,
+    "agentSpread": OKSTRA_DEFECT,
+    "phaseLock": OKSTRA_DEFECT,
+    "declaredCause": ENVIRONMENT_POLICY,
+    "targetSourcePath": TARGET_CODE,
+}
+
+# okstra 가 소유한 표면. 여기서 난 실패는 타겟 코드가 아니라 okstra 배선 문제다.
+# 태스크 워크트리(~/.okstra/worktrees/...)는 제외한다 — 그 디렉터리는 타겟 저장소의
+# 체크아웃이라 거기서 난 실패는 남의 코드에서 난 것이다.
+_OKSTRA_PATH_MARKERS = (
+    "/.okstra/tasks/", "/.okstra/runs/", "/.okstra/decisions/",
+    "/.okstra/project.json", "/.okstra/glossary.md",
+    "/.okstra/recent.jsonl", "/.okstra/active.jsonl", "/.okstra/bin/",
+    "okstra_ctl", "scripts/okstra-",
+)
+# 환경 정책 사안으로 미리 분류된 cause. sandbox-denied 는 실측상 오진이 많아
+# 여기 넣지 않는다 — 프로브 증거 검사는 error_issue.validate_candidate 가 맡는다.
+_ENVIRONMENT_CAUSES = ("auth-failed", "service-unavailable")
+
+_FREETEXT_FIELDS = ("message", "stderrExcerpt", "command")
+
+# 경로 신호가 어느 필드를 읽었는지 알리는 라벨. 이 문자열은 공개 이슈 본문의
+# source 열에 그대로 실리므로 error_issue 의 유출 허용목록이 같은 값을 참조한다 —
+# 여기서 필드가 늘면 라벨과 허용목록이 함께 따라간다.
+FREETEXT_SOURCE = "/".join(_FREETEXT_FIELDS)
+
+
+def _freetext(rec: dict) -> str:
+    """자유 텍스트 필드를 잇되 프로젝트 루트 접두는 지우고 본다.
+
+    `message`·`stderrExcerpt`·`command` 에는 타겟의 절대 프로젝트 루트가 통째로
+    박혀 있다. 루트 경로 자체에 `app/`·`lib/` 같은 조각이 들어 있으면 실패가
+    어디서 났든 `targetSourcePath` 가 켜진다 — 실측에서 `okstraOwnedPath` 가
+    켜진 103개 클러스터 중 86개가 `targetSourcePath` 도 함께 켰고, 그중 83개는
+    사용자의 프로젝트가 `.../FontsNinja/app/` 아래 있다는 이유뿐이었다.
+
+    루트를 지운 텍스트로 계산하면 31개 클러스터의 판정·반대신호가 달라진다.
+    반대 신호는 후보를 `skip` 으로 떨어뜨리므로 이 오발화는 본문 잡음이 아니라
+    진짜 결함을 조용히 묻는다 — 실측 7건의 반대신호 후보 중 4건이 깨끗해지고
+    그중 하나는 `contract-violation` 이다."""
+    root = str(rec.get("_projectRoot", "") or "")
+    parts = []
+    for field in _FREETEXT_FIELDS:
+        value = str(rec.get(field, "") or "")
+        parts.append(value.replace(root, "") if root else value)
+    return " ".join(parts)
+
+
+def _has_okstra_path(rec: dict) -> bool:
+    text = _freetext(rec)
+    return any(marker in text for marker in _OKSTRA_PATH_MARKERS)
+
+
+def _has_target_path(rec: dict) -> bool:
+    """okstra 경로가 함께 잡혀도 단락하지 않는다 — 둘 다 켜두면 모순이
+    conflicting 으로 드러나 사람이 판단할 수 있다. 단락시키면 반대 근거가
+    아예 사라진다."""
+    text = _freetext(rec)
+    return any(seg in text for seg in ("src/", "lib/", "app/", "tests/"))
+
+
+def _distinct(records: list[dict], field: str) -> int:
+    return len({str(r.get(field, "")) for r in records if r.get(field)})
+
+
+def _signal(name: str, value, source: str) -> dict:
+    return {"signal": name, "value": value, "source": source}
+
+
+def compute_signals(records: list[dict]) -> list[dict]:
+    """한 클러스터의 원본 레코드에서 신호를 계산한다."""
+    if not records:
+        return []
+    phases = {str(r.get("phase", "")) for r in records if r.get("phase")}
+    causes = [
+        str(r.get("context", {}).get("cause", ""))
+        for r in records
+        if isinstance(r.get("context"), dict) and r.get("context", {}).get("cause")
+    ]
+    # cause 는 워커가 스스로 적는 값이라, 1건짜리 자기신고가 클러스터 전체를
+    # 환경 사안으로 돌리지 못하게 과반을 요구한다. sandbox-denied 를 아예 뺀 것과
+    # 같은 불신을 나머지 cause 에도 건다.
+    declared = [c for c in causes if c in _ENVIRONMENT_CAUSES]
+    environment_cause = ""
+    if declared:
+        top = max(sorted(set(declared)), key=declared.count)
+        if declared.count(top) * 2 > len(records):
+            environment_cause = top
+    return [
+        _signal("contractViolation",
+                any(r.get("errorType") == "contract-violation" for r in records),
+                "errorType"),
+        _signal("okstraOwnedPath",
+                any(_has_okstra_path(r) for r in records),
+                FREETEXT_SOURCE),
+        _signal("targetSourcePath",
+                any(_has_target_path(r) for r in records),
+                FREETEXT_SOURCE),
+        _signal("taskSpread", _distinct(records, "taskKey"), "taskKey"),
+        _signal("projectSpread", _distinct(records, "_projectRoot"), "_projectRoot"),
+        _signal("agentSpread", _distinct(records, "agent"), "agent"),
+        _signal("phaseLock", len(phases) == 1, "phase"),
+        _signal("declaredCause", environment_cause, "context.cause"),
+    ]
+
+
+def signal_fires(sig: dict) -> bool:
+    """신호가 켜졌는지. 카운트형은 2 이상일 때만 확산 신호로 인정한다.
+
+    공개 함수다 — 등록 직전 게이트(error_issue.validate_candidate)가 같은 판단을
+    다시 걸어야 하는데, 비공개로 두면 그쪽이 자기 판본을 새로 만들면서
+    `taskSpread: 1` 같은 꺼진 신호를 근거로 세는 더 약한 규칙이 된다.
+
+    `value` 가 없는 항목은 꺼진 것으로 본다. 이 함수는 사람이 손으로 고친
+    plan.json 을 읽는 자리에 있어, 필드 하나가 빠졌다고 KeyError 로 터지면
+    등록 루프가 그 자리에서 끊긴다 — 앞의 후보는 이미 올라간 뒤다."""
+    value = sig.get("value")
+    if sig["signal"] in ("taskSpread", "projectSpread", "agentSpread"):
+        return isinstance(value, int) and value >= 2
+    if isinstance(value, bool):
+        return value
+    return bool(value)
+
+
+def classify(signals: list[dict]) -> tuple[str, list[dict], list[dict]]:
+    """(분류, 지지 신호, 반대 신호) 를 돌려준다.
+
+    declaredCause 가 켜지면 환경 정책이 이긴다 — 워커가 명시적으로 분류한
+    사안을 신호 개수로 뒤집지 않는다. 그 외에는 최다 지지 분류를 고르고,
+    다른 분류를 지지하는 신호는 반대 신호로 그대로 노출한다."""
+    fired = [s for s in signals if signal_fires(s)]
+    by_class: dict[str, list[dict]] = {}
+    for sig in fired:
+        by_class.setdefault(SIGNAL_SUPPORT[sig["signal"]], []).append(sig)
+
+    if by_class.get(ENVIRONMENT_POLICY):
+        verdict = ENVIRONMENT_POLICY
+    elif not by_class:
+        verdict = ""
+    else:
+        verdict = max(by_class.items(), key=lambda kv: (len(kv[1]), kv[0]))[0]
+
+    supporting = by_class.get(verdict, [])
+    # okstra-defect 만 공개 이슈가 되므로 그 판정에만 최소 근거 수를 요구하고,
+    # 약한 신호는 세지 않는다. 다른 분류는 후보에서 빠지는 방향이라 근거 하나로도
+    # 해가 없다. supporting 에는 약한 신호도 그대로 담아 이슈 본문에 남긴다.
+    if verdict == OKSTRA_DEFECT:
+        strong = [s for s in supporting if s["signal"] not in WEAK_SIGNALS]
+        alone_is_enough = any(
+            s["signal"] in SELF_SUFFICIENT_SIGNALS for s in strong)
+        if not alone_is_enough and len(strong) < MIN_SUPPORTING_SIGNALS:
+            return "", [], []
+
+    conflicting = [s for s in fired if SIGNAL_SUPPORT[s["signal"]] != verdict]
+    return verdict, supporting, conflicting

package/runtime/python/okstra_ctl/paths.py

@@ -15,6 +15,7 @@ from __future__ import annotations
 
 import os
 import re
+from collections.abc import Callable, Sequence
 from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Optional
@@ -41,9 +42,46 @@ __all__ = [
     "task_runs_dir",
     "container_paths",
     "okstra_home",
+    "find_asset_root",
 ]
 
 
+def find_asset_root(
+    relative: Sequence[str],
+    *,
+    start: Optional[Path] = None,
+    is_present: Callable[[Path], bool] = Path.is_file,
+) -> Optional[Path]:
+    """Return the runtime root that carries ``relative``, or None.
+
+    okstra's assets ship in three layouts that put the same tree at a different
+    depth relative to this package: a repo checkout has `scripts/okstra_ctl/`,
+    the built runtime has `runtime/python/okstra_ctl/`, and an install has
+    `~/.okstra/lib/python/okstra_ctl/` with the asset trees two levels further
+    up at `~/.okstra/`. Probing for the asset therefore beats counting parents,
+    which is right for exactly one of the three.
+
+    Pass ``is_present=Path.is_dir`` when ``relative`` names a directory.
+
+    This reads `OKSTRA_HOME` straight from the environment rather than calling
+    `okstra_home()`, and the difference is load-bearing: `okstra_home()` falls
+    back to `~/.okstra` when the variable is unset, which would let an
+    installed copy shadow the checkout a developer is running from. An unset
+    variable — or one whose tree lacks the asset — falls through to the walk.
+    """
+    override = os.environ.get("OKSTRA_HOME")
+    if override:
+        root = Path(override)
+        if is_present(root.joinpath(*relative)):
+            return root
+
+    here = Path(start or __file__).resolve()
+    for parent in [here, *here.parents]:
+        if is_present(parent.joinpath(*relative)):
+            return parent
+    return None
+
+
 _STAGED_TASK_TYPES = ("implementation", "final-verification")
 # 발견용: bash `find -name 'final-report-*.md'` 와 같은 범위 — seq 이전 세대의
 # 타임스탬프 파일명도 잡아야 옛 번들에서 조용히 실패하지 않는다.