okstra 0.158.1 → 0.160.0

package/runtime/python/okstra_ctl/error_issue.py

@@ -0,0 +1,640 @@
+"""런 이상을 GitHub 이슈 후보로 만들고(plan), 승인 뒤 등록한다(submit).
+
+plan 은 결정적 Python 이고 submit 은 plan.json 만 읽는다 — 승인 화면에서 본
+것과 실제 올라가는 것이 같음을 이 경계가 보장한다.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import hashlib
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from okstra_ctl.error_zip import anonymize, build_clusters, collect_records
+from okstra_ctl.issue_signals import (
+    FREETEXT_SOURCE, MIN_SUPPORTING_SIGNALS, SELF_SUFFICIENT_SIGNALS,
+    SIGNAL_SUPPORT, WEAK_SIGNALS, classify, compute_signals, signal_fires,
+)
+from okstra_ctl.paths import okstra_home
+from okstra_ctl.run_audit import INVARIANT_APPROVAL_NOT_FORGOTTEN, audit_runs
+
+_CONFIG_NAME = "error-issue.json"
+DEFAULT_REPO = "Devonshin/okstra"
+DEFAULT_THRESHOLDS = {"minCount": 3, "recentDays": 14}
+FINGERPRINT_MARKER = "okstra-fingerprint"
+ISSUE_LABEL = "okstra-error-feedback"
+
+# 불변식 하나가 몇 개의 태스크에서 깨져야 okstra 의 결함으로 보는가.
+AUDIT_MIN_TASKS = 2
+
+# 확산돼도 okstra 의 결함이 아닌 불변식. `approval-not-forgotten` 은 사람이
+# 승인을 아직 안 했다는 상태이지 okstra 가 뭘 잘못한 게 아니다 — 실측에서 이
+# 하나가 28개 태스크에서 깨져 있었고, 그대로 두면 "승인해 주세요"가 공개 이슈로
+# 올라간다. 감사 리포트에는 그대로 남고 이슈 후보에서만 빠진다.
+#
+# 이름은 `run_audit` 의 상수를 그대로 쓴다. 여기에 리터럴을 다시 적으면 그쪽이
+# 이름을 바꿀 때 방출부만 따라가고 이 필터는 뚫린 채 남는다 — 스위트는 green 인
+# 상태로 승인 대기가 공개 이슈가 된다.
+NEVER_AN_ISSUE = frozenset({INVARIANT_APPROVAL_NOT_FORGOTTEN})
+
+
+def load_config(home: Path) -> dict:
+    cfg = {"repo": DEFAULT_REPO, **DEFAULT_THRESHOLDS}
+    path = home / _CONFIG_NAME
+    if not path.is_file():
+        return cfg
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return cfg
+    if isinstance(loaded, dict):
+        cfg.update({k: v for k, v in loaded.items() if k in cfg})
+    return cfg
+
+
+def fingerprint(cluster_key_value: str) -> str:
+    return hashlib.sha256(cluster_key_value.encode("utf-8")).hexdigest()[:12]
+
+
+def _parse_ts(value) -> dt.datetime | None:
+    if not value:
+        return None
+    try:
+        parsed = dt.datetime.fromisoformat(str(value))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=dt.timezone.utc)
+
+
+def passes_gate(cluster: dict, *, now: dt.datetime, thresholds: dict) -> bool:
+    """발생 횟수와 최종 관측 시각 두 조건을 모두 만족해야 후보가 된다.
+
+    lastSeen 이 없거나 파싱되지 않으면 신선하다고 가정하지 않고 거부한다 —
+    시각을 모르는 클러스터를 최근 것으로 취급하면 게이트가 무의미해진다."""
+    if int(cluster.get("count", 0)) < int(thresholds["minCount"]):
+        return False
+    last_seen = _parse_ts(cluster.get("lastSeen"))
+    if last_seen is None:
+        return False
+    return (now - last_seen).days <= int(thresholds["recentDays"])
+
+
+def _default_runner(args: list[str]) -> str:
+    proc = subprocess.run(args, capture_output=True, text=True, check=False)
+    if proc.returncode != 0:
+        raise RuntimeError(f"gh failed ({proc.returncode}): {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def gh_run(args: list[str], *, runner=None) -> str:
+    """gh 호출의 유일한 지점. 표준출력을 파싱하지 않고 그대로 돌려준다.
+    테스트는 runner 를 주입해 subprocess 를 우회한다."""
+    run = runner or _default_runner
+    return run(args)
+
+
+def gh_json(args: list[str], *, runner=None):
+    """`--json` 을 준 읽기 전용 조회 전용. 쓰기 명령(issue create/comment)은
+    JSON 이 아니라 생성된 URL 을 출력하므로 여기를 지나면 안 된다 — 지나면
+    이슈가 이미 만들어진 뒤에 크래시하고, 재실행이 중복 이슈를 만든다."""
+    out = gh_run(args, runner=runner)
+    return json.loads(out) if out.strip() else []
+
+
+def find_existing_issue(fp: str, *, repo: str, runner=None) -> dict | None:
+    """지문 마커를 본문에 품은 이슈를 찾는다. 열림/닫힘 모두 대상이다 —
+    닫힌 이슈를 못 보면 같은 결함으로 새 이슈를 또 만들게 된다."""
+    rows = gh_json([
+        "gh", "issue", "list", "--repo", repo, "--label", ISSUE_LABEL,
+        "--state", "all", "--limit", "200",
+        "--json", "number,state,body,comments,createdAt",
+    ], runner=runner)
+    marker = f"<!-- {FINGERPRINT_MARKER}: {fp} -->"
+    for row in rows:
+        if marker in str(row.get("body", "")):
+            # gh 는 코멘트를 오래된 순으로 준다(실측: cli/cli#14089).
+            comments = row.get("comments") or []
+            last_comment_at = str(comments[-1].get("createdAt", "")) if comments else ""
+            return {
+                "number": row.get("number"),
+                "state": str(row.get("state", "")).lower(),
+                "createdAt": str(row.get("createdAt", "")),
+                "lastCommentAt": last_comment_at,
+            }
+    return None
+
+
+def decide_action(existing: dict | None, *, last_seen: str) -> str:
+    """이미 보고한 발생을 다시 알리지 않는 것이 이 판정의 목적이다.
+
+    닫힌 이슈도 같은 규칙을 쓴다. 예전에는 닫혔다는 것만으로 무조건 코멘트를
+    달아, 클러스터가 `recentDays` 안에 머무는 동안 실행할 때마다 같은 재발
+    코멘트가 쌓였다. 마지막 알림 이후의 새 발생만 알리면 재발 통지는 그대로
+    살아 있고 반복만 사라진다.
+
+    비교 기준은 마지막 코멘트, 없으면 이슈 생성 시각이다. 코멘트가 없는 이슈를
+    무조건 comment 로 떨어뜨리면 방금 만든 이슈가 본문에 이미 실린 그 발생을
+    재발로 한 번 더 알린다. 반대로 코멘트 존재 자체를 영구 빗장으로 쓰면 사람이
+    남긴 토론 코멘트 하나가 그 지문을 영원히 침묵시킨다 — 기준은 코멘트가
+    있느냐가 아니라 그 뒤에 새 발생이 있었느냐다."""
+    if existing is None:
+        return "create"
+    baseline = (_parse_ts(existing.get("lastCommentAt"))
+                or _parse_ts(existing.get("createdAt")))
+    seen = _parse_ts(last_seen)
+    if baseline is None or seen is None:
+        return "comment"
+    return "comment" if seen > baseline else "skip"
+
+
+ALLOWED_ACTIONS = frozenset({"create", "comment", "skip"})
+
+# --- 유출 검사: 허용목록 ---------------------------------------------------
+#
+# 금지 목록을 늘리는 방식으로는 이 문제를 못 막는다. `/Users` 를 막으면
+# `/Volumes` 가, 그것을 막으면 `/home` 이, 그 다음엔 소문자·URL 인코딩·상대
+# 태스크 경로(`.project-docs/okstra/tasks/dev-9388/…`)가 남는다. 새 모양을 알게
+# 되는 시점은 언제나 그 한 건이 이미 공개 레포에 올라간 뒤다.
+#
+# 그래서 반대로 건다 — 나가도 되는 모양을 정의하고 나머지는 이유와 함께
+# 거부한다. 검사 대상은 산문 단어가 아니라 **식별자 모양**의 토큰이다. 타겟의
+# 신원이 실제로 실려 나가는 자리가 경로와 티켓 아이디이기 때문이다.
+# 식별자 모양은 두 가지다. 실측 81개 후보 본문으로 고른 값이다.
+_PATH_CHAR = r"[A-Za-z0-9_.<>~@+-]"
+_IDENTIFIER_SHAPES = (
+    # 경로 — 슬래시로 이어진 토큰. 절대·상대를 가리지 않으므로 접두 열거가
+    # 필요 없다. 역슬래시는 구분자로 보지 않는다: 본문에 실리는 JSONL 의 `\n`
+    # 이스케이프가 전부 경로로 잡혀 멀쩡한 후보가 거짓 거부된다.
+    re.compile(rf"{_PATH_CHAR}*(?:/{_PATH_CHAR}+)+"),
+    # 콜론으로 이어진 task-key 모양. 익명화는 `taskKey` 필드만 토큰으로 바꾸므로
+    # 자유 텍스트에 적힌 태스크 키는 그대로 남는다(실측 `jobs:uploadfont` 2건).
+    re.compile(r"(?<![\w:-])[A-Za-z][\w-]{2,}:[A-Za-z][\w-]{2,}"),
+)
+
+# 나가도 되는 식별자. 이 목록 밖의 식별자 모양은 전부 거부된다.
+_ALLOWED_IDENTIFIERS = (
+    re.compile(r"^proj-\d+$"),      # anonymize() 가 프로젝트 루트에 매기는 토큰
+    re.compile(r"^<[a-z]+>$"),      # 익명화 자리표시자 <path> <email> <ip> <token> …
+    re.compile(r"^/(?:Users|home)/<user>$"),          # 마스킹된 홈 접두
+    re.compile(rf"^{re.escape(FREETEXT_SOURCE)}$"),   # 경로 신호의 source 라벨
+    re.compile(r"^(?:file|path):line$"),              # okstra 자신의 인용 관례
+)
+
+
+def _leaks(text: str) -> list[str]:
+    """허용목록 밖의 식별자 토큰을 돌려준다. 비어 있지 않으면 유출이다."""
+    found: list[str] = []
+    for shape in _IDENTIFIER_SHAPES:
+        for token in shape.findall(text):
+            if not token or token in found:
+                continue
+            if any(allowed.match(token) for allowed in _ALLOWED_IDENTIFIERS):
+                continue
+            found.append(token)
+    return found
+
+
+def validate_candidate(candidate: dict) -> list[str]:
+    """등록 직전 검사. 비어 있지 않은 목록이 돌아오면 이 후보는 등록하지 않는다.
+
+    익명화가 앞에서 한 번 돌았다는 사실에 기대지 않고, 바깥으로 나가는
+    마지막 지점에서 다시 막는다."""
+    reasons: list[str] = []
+
+    evidence = candidate.get("evidence") or []
+    if not evidence:
+        reasons.append("evidence is empty — a classification with no evidence never ships")
+
+    # plan.json 은 사람이 손으로 고치는 파일이고, facet 은 원문 인용을 근거로
+    # 덧붙이라고 지시한다. 모양이 어긋난 항목은 사유로 거부한다 — 트레이스백으로
+    # 터지면 그 후보 하나가 아니라 등록 루프 전체가 끊긴다.
+    malformed = [
+        e for e in evidence
+        if not isinstance(e, dict) or not {"signal", "value", "source"} <= set(e)
+    ]
+    if malformed:
+        reasons.append(
+            f"{len(malformed)} evidence entr(ies) missing one of signal/value/source"
+        )
+
+    verdict = str(candidate.get("classification", ""))
+    # classify 와 같은 규칙을 바깥으로 나가는 마지막 지점에서 한 번 더 건다 —
+    # 꺼진 신호는 근거로 세지 않고, 약한 신호도 세지 않으며, 단독 충분 신호는
+    # 최소 수를 우회한다. signal_fires 를 빼먹으면 `taskSpread: 1` 같은 꺼진 신호가
+    # 자리를 채워, classify 가 애초에 거부했을 후보가 이 게이트를 통과한다.
+    supporting = [
+        e for e in evidence
+        if isinstance(e, dict)
+        and SIGNAL_SUPPORT.get(str(e.get("signal", ""))) == verdict
+        and str(e.get("signal", "")) not in WEAK_SIGNALS
+        and signal_fires(e)
+    ]
+    alone_is_enough = any(
+        str(e.get("signal", "")) in SELF_SUFFICIENT_SIGNALS for e in supporting)
+    if evidence and not alone_is_enough and len(supporting) < MIN_SUPPORTING_SIGNALS:
+        reasons.append(
+            f"only {len(supporting)} supporting signal(s) for classification "
+            f"{verdict!r} — {MIN_SUPPORTING_SIGNALS} required"
+        )
+
+    for rec in candidate.get("records") or []:
+        context = rec.get("context") if isinstance(rec.get("context"), dict) else {}
+        if context.get("cause") != "sandbox-denied":
+            continue
+        probes = context.get("causeEvidence") or {}
+        if not (probes.get("targetProbe") and probes.get("controlProbe")):
+            reasons.append(
+                "cause 'sandbox-denied' without both probes — unproven blocking claim"
+            )
+            break
+
+    # action 은 허용목록으로 검사한다. submit_plan 이 인식하지 못한 값을
+    # 코멘트로 흘리면 공개 레포에 글이 올라간다. plan.json 은 사람이 손으로
+    # 고치는 파일이므로 오타 하나가 그 경로를 연다.
+    action = str(candidate.get("action", ""))
+    if action not in ALLOWED_ACTIONS:
+        reasons.append(f"unknown action {action!r} — allowed: {sorted(ALLOWED_ACTIONS)}")
+    if action == "comment":
+        number = (candidate.get("existingIssue") or {}).get("number")
+        if not isinstance(number, int):
+            reasons.append("action 'comment' requires existingIssue.number")
+
+    title = candidate.get("title")
+    body = candidate.get("body")
+    if not isinstance(title, str) or not title.strip():
+        reasons.append("title is empty")
+    if not isinstance(body, str) or not body.strip():
+        reasons.append("body is empty")
+
+    outbound = f"{candidate.get('title', '')}\n{candidate.get('body', '')}"
+    for token in _leaks(outbound):
+        reasons.append(
+            f"leak: {token!r} is not an allowed outbound token — "
+            "only anonymized identifiers may leave this machine"
+        )
+
+    return reasons
+
+
+def _cluster_records(records: list[dict], keys: list[str]) -> dict:
+    grouped: dict[str, list[dict]] = {}
+    for rec, key in zip(records, keys):
+        grouped.setdefault(key, []).append(rec)
+    return grouped
+
+
+def _seen_bounds(records: list[dict]) -> tuple[str, str]:
+    stamps = sorted(str(r.get("ts", "")) for r in records if r.get("ts"))
+    return (stamps[0], stamps[-1]) if stamps else ("", "")
+
+
+def _render_body(*, fp, cluster, clean, verdict, supporting, conflicting,
+                 thresholds, first_seen, last_seen) -> str:
+    """공개 레포로 나가는 본문. 파생됐거나 상한이 있는 값만 싣는다.
+
+    원시 레코드는 **본문에 넣지 않는다.** `_scrub_freetext` 는 슬래시 경로만
+    붕괴시키므로, `stderrExcerpt` 는 타겟의 티켓 아이디·소스 파일명·식별자를
+    그대로 통과시킨다 — 실측 후보 81건 중 14건이 그랬고(`DEV-9044`,
+    `upload.service.ts:L103-111`, `unzip.service.ts`, `UPLOAD_CONCURRENCY`,
+    `idUploadJob`), 등록 직전 게이트는 `leaks == []` 로 통과시켰다.
+
+    모양으로는 `DEV-9426` 과 `gemini-3` 을 가를 수 없다는 것이 실측으로
+    확인됐으므로(허용목록에 티켓 모양을 넣으면 후보 81건 중 28건이 거짓 거부됨),
+    가리려 하지 않고 싣지 않는다. 증거는 사라지지 않는다 — 로컬 `plan.json` 의
+    후보 `records` 와 `okstra error-zip` 아카이브에 그대로 있고, 본문은 그 자리를
+    가리키기만 한다."""
+    sample = clean[0] if clean else {}
+    lines = [
+        f"<!-- {FINGERPRINT_MARKER}: {fp} -->",
+        "",
+        "## What happened",
+        "",
+        f"- errorType: `{cluster['errorType']}`",
+        f"- phase: `{cluster['phase']}`",
+        f"- agent: `{cluster['agent']}`",
+        f"- representative message: `{str(sample.get('message', ''))[:200]}`",
+        "",
+        "## Why this looks like an okstra defect",
+        "",
+        f"Classification: **{verdict}**",
+        "",
+        "| signal | value | source |",
+        "|---|---|---|",
+    ]
+    lines += [f"| `{s['signal']}` | `{s['value']}` | `{s['source']}` |"
+              for s in supporting]
+    if conflicting:
+        lines += [
+            "",
+            "### Signals pointing the other way",
+            "",
+            "| signal | value | source |",
+            "|---|---|---|",
+        ]
+        lines += [f"| `{s['signal']}` | `{s['value']}` | `{s['source']}` |"
+                  for s in conflicting]
+    lines += [
+        "",
+        "## Why it was filed",
+        "",
+        f"- occurrences: {cluster['count']}",
+        f"- distinct projects: {len(cluster['projects'])}",
+        f"- first seen: {first_seen}",
+        f"- last seen: {last_seen}",
+        f"- thresholds applied: minCount={thresholds['minCount']}, "
+        f"recentDays={thresholds['recentDays']}",
+        "",
+        "## Where the raw records are",
+        "",
+        f"The {cluster['count']} underlying error records are not published here — "
+        "their free text carries the reporting project's identifiers. They stay on "
+        "the reporting machine: this candidate's `records` in the local "
+        "`error-issue plan.json`, and the anonymized archive from "
+        "`okstra error-zip`.",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def _render_audit_body(*, fp, invariant, task_keys, projects, evidence,
+                       members) -> str:
+    """감사 후보의 공개 본문 — 경로도 태스크 아이디도 싣지 않는다.
+
+    감사 이슈가 주장하는 것은 "okstra 가 이 불변식을 N개 태스크에서 못 지킨다"
+    이고, 그 주장에 필요한 재료는 불변식 이름·건수·관측된 task-type 뿐이다.
+
+    위반의 `detail` 과 `source` 는 그 자리에 오면 안 된다. 둘 다 타겟의 디렉터리
+    관례와 티켓 아이디를 문자열로 품고 있어(실측:
+    `.project-docs/okstra/tasks/dev-9388/dev-9426/runs/…`) 공개 레포에 나가는
+    순간 그 회사의 내부 명명이 그대로 공개된다. 그 값이 필요한 사람은 로컬
+    `run-audit` 리포트를 보면 된다 — 거기엔 둘 다 그대로 남는다."""
+    by_task_type: dict[str, int] = {}
+    for member in members:
+        name = str(member.get("taskType", "")) or "(unknown)"
+        by_task_type[name] = by_task_type.get(name, 0) + 1
+    return "\n".join([
+        f"<!-- {FINGERPRINT_MARKER}: {fp} -->",
+        "",
+        "## What the audit found",
+        "",
+        f"Invariant `{invariant}` was violated {len(members)} times in "
+        f"{len(task_keys)} tasks across {len(projects)} projects.",
+        "",
+        "## Why this looks like an okstra defect",
+        "",
+        "Classification: **okstra-defect**",
+        "",
+        "| signal | value | source |",
+        "|---|---|---|",
+        *[f"| `{e['signal']}` | `{e['value']}` | `{e['source']}` |" for e in evidence],
+        "",
+        "## Observations",
+        "",
+        "| task type | violations |",
+        "|---|---:|",
+        *[f"| `{name}` | {count} |"
+          for name, count in sorted(by_task_type.items())],
+        "",
+    ])
+
+
+def audit_candidates(violations: list[dict], *, min_tasks: int) -> list[dict]:
+    """불변식 위반을 확산 기준으로 걸러 후보로 만든다.
+
+    한 태스크에서만 깨진 불변식은 그 태스크의 상태이지 okstra 의 결함이 아니다.
+    여러 태스크에서 같은 불변식이 반복해 깨질 때만 okstra 가 그 상황을 못
+    막고 있다는 뜻이 된다."""
+    grouped: dict[str, list[dict]] = {}
+    for v in violations:
+        if v["invariant"] in NEVER_AN_ISSUE:
+            continue
+        grouped.setdefault(v["invariant"], []).append(v)
+
+    out = []
+    for invariant, members in sorted(grouped.items()):
+        task_keys = sorted({m["taskKey"] for m in members if m.get("taskKey")})
+        if len(task_keys) < min_tasks:
+            continue
+        projects = sorted({m["projectRoot"] for m in members if m.get("projectRoot")})
+        # 감사 후보의 시계. `run_audit` 이 위반마다 붙인 관측 시각 중 가장 최근
+        # 것이 이 불변식의 `lastSeen` 이다 — 이것이 있어야 감사 후보도 에러 로그
+        # 후보와 같은 중복 판정을 쓸 수 있다.
+        observed = [ts for ts in (_parse_ts(m.get("observedAt")) for m in members)
+                    if ts is not None]
+        last_seen = max(observed).isoformat() if observed else ""
+        # invariantViolated 를 함께 싣는다 — 확산이 한 프로젝트 안에 머무르면
+        # projectSpread 가 발화하지 않아 지지 신호가 하나로 떨어지고,
+        # validate_candidate 의 최소 근거 수에 걸려 감사 후보가 통째로 거부된다.
+        evidence = [
+            {"signal": "invariantViolated", "value": invariant, "source": "run-audit"},
+            {"signal": "taskSpread", "value": len(task_keys), "source": "run-manifest.taskKey"},
+            {"signal": "projectSpread", "value": len(projects), "source": "run-index.projectRoot"},
+        ]
+        fp = fingerprint(f"run-audit|{invariant}")
+        out.append({
+            "fingerprint": fp,
+            "origin": "run-audit",
+            "clusterKey": f"run-audit|{invariant}",
+            "count": len(members),
+            "firstSeen": min(observed).isoformat() if observed else "",
+            "lastSeen": last_seen,
+            "signals": evidence,
+            "classification": "okstra-defect",
+            "evidence": evidence,
+            "conflictingSignals": [],
+            "existingIssue": None,
+            "action": "create",
+            "records": [],
+            "title": f"[run-audit] invariant {invariant} violated across "
+                     f"{len(task_keys)} tasks",
+            "body": _render_audit_body(
+                fp=fp, invariant=invariant, task_keys=task_keys,
+                projects=projects, evidence=evidence, members=members),
+        })
+    return out
+
+
+def build_plan(home: Path, *, now: dt.datetime, runner=None) -> dict:
+    cfg = load_config(home)
+    thresholds = {"minCount": cfg["minCount"], "recentDays": cfg["recentDays"]}
+    records, stats = collect_records(home)
+    clusters, keys = build_clusters(records, project_field="_projectRoot")
+    grouped = _cluster_records(records, keys)
+
+    candidates = []
+    below_gate = 0
+    not_defect = 0
+    conflicted = 0
+    for cluster in clusters:
+        members = grouped.get(cluster["key"], [])
+        first_seen, last_seen = _seen_bounds(members)
+        enriched = {**cluster, "lastSeen": last_seen}
+        if not passes_gate(enriched, now=now, thresholds=thresholds):
+            below_gate += 1
+            continue
+        signals = compute_signals(members)
+        verdict, supporting, conflicting = classify(signals)
+        if verdict != "okstra-defect":
+            not_defect += 1
+            continue
+        # 반대 신호가 있는 클러스터는 버리지 않고 skip 후보로 남긴다. 조용히
+        # 버리면 targetSourcePath 가 stderr 의 `tests/` 한 조각에 발화한 것만으로
+        # 진짜 계약 위반이 사라지고, 사람은 그런 일이 있었는지도 모른다.
+        if conflicting:
+            conflicted += 1
+        fp = fingerprint(cluster["key"])
+        existing = find_existing_issue(fp, repo=cfg["repo"], runner=runner)
+        # 익명화는 여기서 한 번만 돌리고 title 과 body 가 그 결과를 공유한다.
+        # title 이 raw sample 을 쓰면 절대경로가 그대로 실려 submit 의 유출 검사에서
+        # 전량 거부된다 — 프로젝트는 보통 /Users/… 아래 있기 때문이다.
+        clean, _ = anonymize(members)
+        sample_message = str(clean[0].get("message", "")) if clean else ""
+        candidates.append({
+            "fingerprint": fp,
+            "origin": "error-log",
+            "clusterKey": cluster["key"],
+            "count": cluster["count"],
+            "firstSeen": first_seen,
+            "lastSeen": last_seen,
+            "signals": signals,
+            "classification": verdict,
+            "evidence": supporting,
+            "conflictingSignals": conflicting,
+            "existingIssue": existing,
+            "action": ("skip" if conflicting
+                       else decide_action(existing, last_seen=last_seen)),
+            "records": members,
+            "title": f"[{cluster['errorType']}] {cluster['phase']}: "
+                     f"{sample_message[:60]}",
+            "body": _render_body(
+                fp=fp, cluster=cluster, clean=clean, verdict=verdict,
+                supporting=supporting, conflicting=conflicting,
+                thresholds=thresholds, first_seen=first_seen, last_seen=last_seen,
+            ),
+        })
+
+    for cand in audit_candidates(audit_runs(home, now=now), min_tasks=AUDIT_MIN_TASKS):
+        existing = find_existing_issue(cand["fingerprint"], repo=cfg["repo"],
+                                       runner=runner)
+        cand["existingIssue"] = existing
+        # 감사 후보도 에러 로그 후보와 같은 판정을 쓴다. 위반이 `observedAt` 을
+        # 들고 오면서 감사 경로에도 시계가 생겼고, 특수 분기 셋이 이 한 줄로
+        # 접힌다 — 분기를 따로 두는 동안 열린 이슈는 영영 침묵하고 닫힌 이슈는
+        # 사람의 토론 코멘트 하나에 영구히 잠겼다.
+        cand["action"] = decide_action(existing, last_seen=cand["lastSeen"])
+        candidates.append(cand)
+
+    return {
+        "schemaVersion": "1.0",
+        "generatedAt": now.isoformat(),
+        "repo": cfg["repo"],
+        "thresholds": thresholds,
+        "stats": {
+            "runCount": stats["runCount"],
+            "unreachableRuns": stats["unreachableRuns"],
+            "clusterCount": len(clusters),
+            "belowGate": below_gate,
+            "notOkstraDefect": not_defect,
+            "conflicted": conflicted,
+        },
+        "candidates": candidates,
+    }
+
+
+def _submit_one(cand: dict, *, repo: str, runner, result: dict) -> None:
+    action = str(cand.get("action", ""))
+    if action == "skip":
+        result["skipped"] += 1
+        return
+    reasons = validate_candidate(cand)
+    if reasons:
+        result["rejected"] += 1
+        result["rejections"].append(
+            {"fingerprint": cand.get("fingerprint"), "reasons": reasons})
+        return
+    # 허용목록 분기 — 인식하지 못한 action 이 코멘트로 흘러 공개 레포에
+    # 글이 올라가는 일이 없어야 한다. validate_candidate 가 이미 action 을
+    # 검사하므로 여기 도달하는 값은 create/comment 뿐이다.
+    if action == "create":
+        gh_run(["gh", "issue", "create", "--repo", repo,
+                "--label", ISSUE_LABEL, "--title", cand["title"],
+                "--body", cand["body"]], runner=runner)
+        result["created"] += 1
+    else:
+        number = str(cand["existingIssue"]["number"])
+        gh_run(["gh", "issue", "comment", number, "--repo", repo,
+                "--body", cand["body"]], runner=runner)
+        result["commented"] += 1
+
+
+def submit_plan(plan: dict, *, repo: str, runner=None) -> dict:
+    """plan.json 만 보고 등록한다. 여기서 스스로 만들어내는 값은 사람이 승인한
+    화면에 없던 값이므로, 목적지(repo)까지 포함해 전부 파일에서 온다.
+
+    후보 하나의 실패는 그 후보에서 멈춘다. 루프 밖으로 예외가 나가면 앞에서
+    이미 등록된 이슈들이 요약도 없이 사라진다 — 사람은 무엇이 올라갔는지 모른 채
+    재실행하고, plan.json 의 action 은 여전히 `create` 라 같은 이슈가 한 번 더
+    올라간다. 실측 재현: 두 번째 후보의 근거 항목 하나에 `value` 가 없어
+    KeyError 로 끊겼고, 그 시점에 gh 호출은 이미 한 번 나간 뒤였다."""
+    result = {"created": 0, "commented": 0, "skipped": 0, "rejected": 0,
+              "failed": 0, "rejections": [], "failures": []}
+    for cand in plan.get("candidates", []):
+        try:
+            _submit_one(cand, repo=repo, runner=runner, result=result)
+        except Exception as exc:  # noqa: BLE001 — 어떤 실패도 루프를 끊지 못한다
+            result["failed"] += 1
+            result["failures"].append({
+                "fingerprint": (cand.get("fingerprint")
+                                if isinstance(cand, dict) else None),
+                "error": f"{type(exc).__name__}: {exc}",
+            })
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra error-issue",
+        description="런 이상을 GitHub 이슈 후보로 만들고(plan) 승인 뒤 등록한다(submit).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    plan_cmd = sub.add_parser("plan", help="후보와 근거를 담은 plan.json 을 만든다")
+    plan_cmd.add_argument("--out", required=True, help="plan.json 출력 경로")
+    submit_cmd = sub.add_parser("submit", help="승인된 plan.json 을 등록한다")
+    submit_cmd.add_argument("--plan", required=True, help="plan.json 경로")
+    args = parser.parse_args(argv)
+
+    home = okstra_home()
+    if args.command == "plan":
+        plan = build_plan(home, now=dt.datetime.now(dt.timezone.utc))
+        out = Path(args.out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(plan, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(json.dumps({
+            "planPath": str(out),
+            "candidateCount": len(plan["candidates"]),
+            **plan["stats"],
+        }, ensure_ascii=False, indent=2))
+        return 0
+
+    plan = json.loads(Path(args.plan).read_text(encoding="utf-8"))
+    repo = str(plan.get("repo", ""))
+    if not repo:
+        # 목적지는 사람이 승인한 화면에 반드시 있어야 할 값이다. 기본값으로
+        # 채우면 검토되지 않은 공개 레포에 글이 올라간다.
+        print(json.dumps({
+            "error": "plan.json has no 'repo' — refusing to pick a destination",
+        }, ensure_ascii=False, indent=2))
+        return 1
+    result = submit_plan(plan, repo=repo)
+    # 부분 요약이라도 반드시 나가야 한다 — 무엇이 이미 올라갔는지 모르는 채로
+    # 재실행하는 것이 중복 이슈를 만드는 경로다.
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 1 if result["rejected"] or result["failed"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))