okstra 0.102.2 → 0.102.3

package/docs/superpowers/plans/2026-06-20-error-feedback-loop.md

@@ -1,1019 +0,0 @@
-# 에러 환류 루프 (cross-project → okstra 자가수정) 구현 계획
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** 머신 내 모든 타겟 프로젝트에 흩어진 okstra 실행 에러를 cross-project 로 수집·집계·익명화해 `.zip` 으로 묶는 `okstra error-zip` facet 과, 그 zip 을 okstra 자신을 고치는 error-analysis brief 로 변환하는 `okstra-brief` variant 를 추가한다.
-
-**Architecture:** 수집·집계·익명화·zip 생성은 결정적 Python(`scripts/okstra_ctl/error_zip.py`)이 맡고, 기존 `error_report.py` 의 글롭/파싱/집계 코어를 공용 모듈로 추출해 공유한다. Node 래퍼(`src/commands/inspect/error-zip.mjs`)는 python 모듈을 spawn 하는 얇은 어댑터이며, `okstra-inspect` SKILL 에 facet 으로 노출한다. 수정은 신규 phase 없이 기존 `error-analysis → implementation-planning → implementation` lifecycle 을 재사용한다.
-
-**Tech Stack:** Python 3 (stdlib `json`/`pathlib`/`zipfile`/`argparse`), Node ES modules, pytest, okstra 빌드(`npm run build`).
-
-## Global Constraints
-
-- **runtime/ 직접 수정 금지** — `runtime/python/`, `runtime/` 전체는 빌드 산출물. 소스는 `scripts/`·`src/`·`skills/` 만 고치고, 마지막에 `npm run build` 로 `runtime/` 동기화. (CLAUDE.md "runtime/ 은 build output")
-- **errorType 비결합(data-driven)** — 집계·클러스터링·익명화는 특정 errorType 값(`tool-failure`/`cli-failure`/`contract-violation`)에 case 분기하지 않는다. errorType 은 레코드에서 읽은 값을 그대로 그룹 키로 쓴다. errorType 목록이 필요한 유일한 지점은 `scripts/okstra-error-log.py:18` 의 `ALLOWED_ERROR_TYPES` 를 import 해 참조한다 — error_zip 코드에 목록을 재정의하지 않는다.
-- **익명화는 allowlist 기반** — 출력 레코드에 포함할 필드를 명시 화이트리스트로 정하고, 그 외 키는 드롭한다. (denylist 금지)
-- **수집기는 읽기 전용** — 타겟의 `.okstra/` 정본 JSONL 을 삭제·이동·수정하지 않는다.
-- **문서/주석 한국어** — SKILL 본문, 코드 주석의 산문은 한국어. 코드 식별자·경로·CLI 인자는 영어.
-- **단일참조** — recent/active 읽기는 `okstra_ctl.jsonl.read_jsonl` / `okstra_ctl.paths.okstra_home` 재사용. 글롭/집계는 신규 `error_log_core` 공용 모듈 1곳.
-- **함수 50줄 상한** — 신규/대폭수정 함수는 유효 50줄 이하. 초과 시 분할.
-
----
-
-### Task 1: 글롭/파싱/집계 코어를 공용 모듈로 추출
-
-`error_report.py` 의 순수·읽기전용 함수(`_glob_error_logs`, `_parse_records`, `_tally`, `_rows`, `_aggregate`)를 신규 `error_log_core.py` 로 옮기고, `error_report.py` 는 거기서 import 한다. 동작 변화 없는 리팩터 — 기존 테스트가 green 으로 남아야 한다.
-
-**Files:**
-- Create: `scripts/okstra_ctl/error_log_core.py`
-- Modify: `scripts/okstra_ctl/error_report.py:18-70` (함수 정의 제거 후 import 로 대체)
-- Test: `tests/inspect/test_error_log_core.py` (신규), `tests/inspect/test_okstra_error_report.py` (기존, 회귀)
-
-**Interfaces:**
-- Produces:
-  - `glob_error_logs(task_root: Path) -> list[Path]`
-  - `parse_records(paths: list[Path]) -> tuple[list[dict], int]` — 각 dict 에 `_sourceLog`(str 절대경로) 주입
-  - `tally(records: list[dict], key: str) -> dict[str, int]`
-  - `rows(counts: dict[str, int], label: str) -> list[dict]`
-  - `aggregate(records: list[dict]) -> dict` — `{errorCount, runCount, byErrorType, bySource, byPhase, byAgent}`
-
-- [ ] **Step 1: 코어 단위 테스트 작성 (실패하도록)**
-
-Create `tests/inspect/test_error_log_core.py`:
-
-```python
-import json
-import sys
-from pathlib import Path
-from _paths import REPO_ROOT
-
-LIB_DIR = REPO_ROOT / "scripts"
-if str(LIB_DIR) not in sys.path:
-    sys.path.insert(0, str(LIB_DIR))
-
-from okstra_ctl import error_log_core as core
-
-
-def _write_log(task_root: Path, run_seg: str, seq: str, records: list[dict]) -> Path:
-    log_dir = task_root / "runs" / run_seg / "logs"
-    log_dir.mkdir(parents=True, exist_ok=True)
-    path = log_dir / f"errors-{run_seg.split('/')[0]}-{seq}.jsonl"
-    with path.open("w", encoding="utf-8") as fh:
-        for rec in records:
-            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
-    return path
-
-
-def test_glob_finds_flat_and_staged(tmp_path):
-    _write_log(tmp_path, "implementation", "001", [{"errorType": "x"}])
-    _write_log(tmp_path, "implementation/stage-1", "001", [{"errorType": "y"}])
-    found = core.glob_error_logs(tmp_path)
-    assert len(found) == 2
-
-
-def test_parse_injects_source_log_and_counts_skips(tmp_path):
-    p = _write_log(tmp_path, "implementation", "001", [{"errorType": "a"}])
-    p.open("a", encoding="utf-8").write("not-json\n")
-    records, skipped = core.parse_records([p])
-    assert len(records) == 1
-    assert skipped == 1
-    assert records[0]["_sourceLog"] == str(p)
-
-
-def test_aggregate_is_errortype_agnostic(tmp_path):
-    records = [
-        {"errorType": "brand-new-type", "source": "s", "phase": "p", "agent": "a", "_sourceLog": "L1"},
-        {"errorType": "brand-new-type", "source": "s", "phase": "p", "agent": "a", "_sourceLog": "L1"},
-    ]
-    agg = core.aggregate(records)
-    assert agg["errorCount"] == 2
-    assert agg["byErrorType"] == {"brand-new-type": 2}
-    assert agg["runCount"] == 1
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/inspect/test_error_log_core.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'okstra_ctl.error_log_core'`
-
-- [ ] **Step 3: 코어 모듈 작성**
-
-Create `scripts/okstra_ctl/error_log_core.py` (기존 `error_report.py:18-70` 의 본문을 public 이름으로 그대로 이전):
-
-```python
-"""errors-*.jsonl 글롭·파싱·집계 공용 코어 (read-only).
-
-error_report(단일 task)와 error_zip(cross-project)이 공유한다.
-errorType 값에 분기하지 않는 data-driven 집계.
-"""
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-
-def glob_error_logs(task_root: Path) -> list[Path]:
-    runs = task_root / "runs"
-    if not runs.exists():
-        return []
-    flat = runs.glob("*/logs/errors-*.jsonl")
-    staged = runs.glob("*/stage-*/logs/errors-*.jsonl")
-    return sorted(set(flat) | set(staged))
-
-
-def parse_records(paths: list[Path]) -> tuple[list[dict], int]:
-    records: list[dict] = []
-    skipped = 0
-    for path in paths:
-        for line in path.read_text(encoding="utf-8").splitlines():
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                rec = json.loads(line)
-            except Exception:
-                skipped += 1
-                continue
-            if isinstance(rec, dict):
-                rec["_sourceLog"] = str(path)
-                records.append(rec)
-            else:
-                skipped += 1
-    return records, skipped
-
-
-def tally(records: list[dict], key: str) -> dict:
-    out: dict[str, int] = {}
-    for rec in records:
-        name = str(rec.get(key, ""))
-        out[name] = out.get(name, 0) + 1
-    return out
-
-
-def rows(counts: dict, label: str) -> list[dict]:
-    return [
-        {label: name, "count": n}
-        for name, n in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
-    ]
-
-
-def aggregate(records: list[dict]) -> dict:
-    return {
-        "errorCount": len(records),
-        "runCount": len({rec.get("_sourceLog", "") for rec in records}),
-        "byErrorType": tally(records, "errorType"),
-        "bySource": tally(records, "source"),
-        "byPhase": rows(tally(records, "phase"), "phase"),
-        "byAgent": rows(tally(records, "agent"), "agent"),
-    }
-```
-
-- [ ] **Step 4: error_report.py 를 코어 import 로 전환**
-
-In `scripts/okstra_ctl/error_report.py`, 기존 `_glob_error_logs`/`_parse_records`/`_tally`/`_rows`/`_aggregate` 정의를 삭제하고 상단 import 부에 추가:
-
-```python
-from okstra_ctl.error_log_core import (
-    glob_error_logs,
-    parse_records,
-    aggregate,
-)
-```
-
-그리고 `build_and_write` 내부 호출부를 새 이름으로 교체:
-- `_glob_error_logs(task_root)` → `glob_error_logs(task_root)`
-- `_parse_records(paths)` → `parse_records(paths)`
-- `_aggregate(records)` → `aggregate(records)`
-
-(`render_markdown`, `_md_table` 등 렌더 함수는 error_report 에 그대로 둔다 — 코어가 아님.)
-
-- [ ] **Step 5: 코어 + 회귀 테스트 통과 확인**
-
-Run: `python3 -m pytest tests/inspect/test_error_log_core.py tests/inspect/test_okstra_error_report.py -v`
-Expected: PASS (신규 3개 + 기존 error_report 테스트 전부)
-
-- [ ] **Step 6: 커밋**
-
-```bash
-git add scripts/okstra_ctl/error_log_core.py scripts/okstra_ctl/error_report.py tests/inspect/test_error_log_core.py
-git commit -m "refactor(inspect): errors 로그 글롭/집계 코어를 error_log_core 로 추출"
-```
-
----
-
-### Task 2: cross-project run-디렉터리 수집 reader
-
-글로벌 run-index(`recent.jsonl`+`active.jsonl`)를 읽어 모든 타겟의 run 디렉터리를 복원하고, 그 밑 errors 로그를 모아 레코드로 파싱한다. 도달 불가(프로젝트 삭제) run 은 skip + 카운트.
-
-**Files:**
-- Create: `scripts/okstra_ctl/error_zip.py`
-- Test: `tests/inspect/test_okstra_error_zip.py` (신규)
-
-**Interfaces:**
-- Consumes: `error_log_core.parse_records` (Task 1), `okstra_ctl.jsonl.read_jsonl`, `okstra_ctl.paths.okstra_home`
-- Produces:
-  - `collect_records(home: Path) -> tuple[list[dict], dict]` — `(records, stats)` 에서 `stats = {"runCount": int, "unreachableRuns": int, "projectRoots": list[str]}`. 각 record 는 `parse_records` 의 `_sourceLog` + 신규 `_projectRoot`(str) 키를 가짐.
-
-- [ ] **Step 1: 수집 테스트 작성 (실패하도록)**
-
-Create `tests/inspect/test_okstra_error_zip.py`:
-
-```python
-import json
-import sys
-from pathlib import Path
-from _paths import REPO_ROOT
-
-LIB_DIR = REPO_ROOT / "scripts"
-if str(LIB_DIR) not in sys.path:
-    sys.path.insert(0, str(LIB_DIR))
-
-from okstra_ctl import error_zip
-from okstra_ctl.jsonl import append_jsonl
-from okstra_ctl.paths import okstra_home
-
-
-def _rec(**over) -> dict:
-    base = {
-        "ts": "2026-06-17T01:00:00+00:00",
-        "taskKey": "projA:g:DEV-1",
-        "phase": "implementation",
-        "agent": "claude-worker",
-        "agentRole": "worker",
-        "source": "worker-reported",
-        "errorType": "cli-failure",
-        "command": "pytest",
-        "exitCode": 1,
-        "message": "boom",
-        "stderrExcerpt": "trace...",
-    }
-    base.update(over)
-    return base
-
-
-def _seed_project(project_root: Path, run_dir_rel: str, records: list[dict]) -> None:
-    log_dir = project_root / run_dir_rel / "logs"
-    log_dir.mkdir(parents=True, exist_ok=True)
-    seq_name = Path(run_dir_rel).name
-    path = log_dir / f"errors-{seq_name}-001.jsonl"
-    with path.open("w", encoding="utf-8") as fh:
-        for rec in records:
-            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
-
-
-def _index_row(project_root: Path, run_dir_rel: str) -> dict:
-    return {
-        "runId": "r1", "projectId": "projA", "projectRoot": str(project_root),
-        "taskGroup": "g", "taskId": "DEV-1", "taskKey": "g/DEV-1",
-        "taskType": "implementation", "runSeq": 1, "status": "done",
-        "startedAt": "2026-06-17T01:00:00+00:00", "finishedAt": None,
-        "runDirRel": run_dir_rel,
-    }
-
-
-def test_collect_records_across_two_projects(tmp_path):
-    home = okstra_home()
-    p1 = tmp_path / "proj1"
-    p2 = tmp_path / "proj2"
-    rel1 = ".okstra/tasks/g/DEV-1/runs/implementation"
-    rel2 = ".okstra/tasks/g/DEV-2/runs/implementation"
-    _seed_project(p1, rel1, [_rec(), _rec(errorType="tool-failure")])
-    _seed_project(p2, rel2, [_rec(taskKey="projB:g:DEV-2")])
-    append_jsonl(home / "recent.jsonl", _index_row(p1, rel1))
-    append_jsonl(home / "recent.jsonl", _index_row(p2, rel2))
-
-    records, stats = error_zip.collect_records(home)
-    assert len(records) == 3
-    assert stats["runCount"] == 2
-    assert stats["unreachableRuns"] == 0
-    assert set(stats["projectRoots"]) == {str(p1), str(p2)}
-
-
-def test_collect_skips_unreachable_project(tmp_path):
-    home = okstra_home()
-    gone = tmp_path / "deleted-project"
-    rel = ".okstra/tasks/g/DEV-1/runs/implementation"
-    append_jsonl(home / "recent.jsonl", _index_row(gone, rel))
-    records, stats = error_zip.collect_records(home)
-    assert records == []
-    assert stats["unreachableRuns"] == 1
-```
-
-(`append_jsonl` 시그니처 확인: `okstra_ctl.jsonl.append_jsonl(path: Path, row: dict)`. 다르면 Step 3 에서 맞춘다.)
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'okstra_ctl.error_zip'`
-
-- [ ] **Step 3: 수집 reader 작성**
-
-Create `scripts/okstra_ctl/error_zip.py`:
-
-```python
-"""cross-project errors-*.jsonl 수집·집계·익명화·zip 생성 (read-only).
-
-글로벌 run-index(recent/active)를 순회해 모든 타겟의 에러 로그를 모은다.
-errorType 값에 분기하지 않는 data-driven 처리.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-from okstra_ctl.error_log_core import parse_records
-from okstra_ctl.jsonl import read_jsonl
-
-
-def _run_dirs(home: Path) -> list[tuple[str, Path]]:
-    rows = read_jsonl(home / "recent.jsonl") + read_jsonl(home / "active.jsonl")
-    seen: set[tuple[str, str]] = set()
-    out: list[tuple[str, Path]] = []
-    for row in rows:
-        project_root = str(row.get("projectRoot", ""))
-        run_dir_rel = str(row.get("runDirRel", ""))
-        if not project_root or not run_dir_rel:
-            continue
-        key = (project_root, run_dir_rel)
-        if key in seen:
-            continue
-        seen.add(key)
-        out.append((project_root, Path(project_root) / run_dir_rel))
-    return out
-
-
-def _logs_in_run_dir(run_dir: Path) -> list[Path]:
-    flat = run_dir.glob("logs/errors-*.jsonl")
-    staged = run_dir.glob("stage-*/logs/errors-*.jsonl")
-    return sorted(set(flat) | set(staged))
-
-
-def collect_records(home: Path) -> tuple[list[dict], dict]:
-    records: list[dict] = []
-    project_roots: set[str] = set()
-    reachable = 0
-    unreachable = 0
-    for project_root, run_dir in _run_dirs(home):
-        if not run_dir.exists():
-            unreachable += 1
-            continue
-        logs = _logs_in_run_dir(run_dir)
-        if not logs:
-            continue
-        reachable += 1
-        recs, _ = parse_records(logs)
-        for rec in recs:
-            rec["_projectRoot"] = project_root
-            records.append(rec)
-        project_roots.add(project_root)
-    stats = {
-        "runCount": reachable,
-        "unreachableRuns": unreachable,
-        "projectRoots": sorted(project_roots),
-    }
-    return records, stats
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py -v`
-Expected: PASS (2개). `append_jsonl` 시그니처가 다르면 테스트의 호출을 실제 시그니처에 맞춘 뒤 재실행.
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/error_zip.py tests/inspect/test_okstra_error_zip.py
-git commit -m "feat(inspect): error-zip cross-project run-디렉터리 수집 reader"
-```
-
----
-
-### Task 3: allowlist 기반 익명화
-
-cross-project 레코드의 타겟 고유 정보를 축약한다. projectRoot 목록을 안정 토큰(`proj-1`, `proj-2`...)으로 매핑하고, 절대경로 문자열을 토큰으로 치환하며, 출력 필드를 화이트리스트로 제한한다.
-
-**Files:**
-- Modify: `scripts/okstra_ctl/error_zip.py`
-- Test: `tests/inspect/test_okstra_error_zip.py`
-
-**Interfaces:**
-- Consumes: `collect_records` 출력 (Task 2)
-- Produces:
-  - `KEEP_FIELDS: tuple[str, ...]` — 보존 필드 화이트리스트
-  - `anonymize(records: list[dict]) -> tuple[list[dict], dict]` — `(clean_records, project_token_map)`. project_token_map = `{projectRoot: token}`.
-
-- [ ] **Step 1: 익명화 테스트 작성 (실패하도록)**
-
-Append to `tests/inspect/test_okstra_error_zip.py`:
-
-```python
-def test_anonymize_tokenizes_paths_and_keeps_allowlist():
-    records = [
-        {
-            "ts": "2026-06-17T01:00:00+00:00",
-            "taskKey": "projA:g:DEV-1",
-            "phase": "implementation", "agent": "claude-worker",
-            "agentRole": "worker", "source": "worker-reported",
-            "errorType": "cli-failure", "command": "pytest",
-            "exitCode": 1, "message": "fail at /Users/me/proj1/src/a.py",
-            "stderrExcerpt": "trace /Users/me/proj1/x",
-            "_sourceLog": "/Users/me/proj1/.okstra/tasks/g/DEV-1/runs/implementation/logs/errors-implementation-001.jsonl",
-            "_projectRoot": "/Users/me/proj1",
-            "secretInternalField": "DROP-ME",
-        }
-    ]
-    clean, token_map = error_zip.anonymize(records)
-    rec = clean[0]
-    assert token_map == {"/Users/me/proj1": "proj-1"}
-    assert "secretInternalField" not in rec
-    assert "/Users/me/proj1" not in rec["message"]
-    assert "proj-1" in rec["message"]
-    assert rec["errorType"] == "cli-failure"      # data-driven 값 보존
-    assert rec["sourceProject"] == "proj-1"
-    assert rec["taskKey"] == "proj-1:g:DEV-1"      # projectId 세그 치환
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py::test_anonymize_tokenizes_paths_and_keeps_allowlist -v`
-Expected: FAIL — `AttributeError: module 'okstra_ctl.error_zip' has no attribute 'anonymize'`
-
-- [ ] **Step 3: 익명화 구현**
-
-Append to `scripts/okstra_ctl/error_zip.py`:
-
-```python
-KEEP_FIELDS = (
-    "ts", "taskKey", "phase", "agent", "agentRole", "source",
-    "errorType", "command", "exitCode", "message", "stderrExcerpt",
-)
-
-
-def _token_map(records: list[dict]) -> dict:
-    roots = sorted({str(r.get("_projectRoot", "")) for r in records if r.get("_projectRoot")})
-    return {root: f"proj-{i}" for i, root in enumerate(roots, start=1)}
-
-
-def _scrub(value: object, token_map: dict) -> object:
-    if not isinstance(value, str):
-        return value
-    out = value
-    for root, token in token_map.items():
-        if root:
-            out = out.replace(root, token)
-    return out
-
-
-def anonymize(records: list[dict]) -> tuple[list[dict], dict]:
-    token_map = _token_map(records)
-    clean: list[dict] = []
-    for rec in records:
-        root = str(rec.get("_projectRoot", ""))
-        token = token_map.get(root, "proj-?")
-        item = {k: _scrub(rec.get(k), token_map) for k in KEEP_FIELDS if k in rec}
-        task_key = str(rec.get("taskKey", ""))
-        if ":" in task_key:
-            item["taskKey"] = token + task_key[task_key.index(":"):]
-        item["sourceProject"] = token
-        clean.append(item)
-    return clean, token_map
-```
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py -v`
-Expected: PASS (수집 2개 + 익명화 1개)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/error_zip.py tests/inspect/test_okstra_error_zip.py
-git commit -m "feat(inspect): error-zip allowlist 기반 레코드 익명화"
-```
-
----
-
-### Task 4: 클러스터 집계 + markdown 리포트 렌더
-
-익명화된 레코드를 (errorType + phase + agent + 정규화된 message) 동일성으로 클러스터링하고, 빈도순 집계 markdown 을 만든다. errorType 은 값 비교만 — case 분기 없음.
-
-**Files:**
-- Modify: `scripts/okstra_ctl/error_zip.py`
-- Test: `tests/inspect/test_okstra_error_zip.py`
-
-**Interfaces:**
-- Consumes: `anonymize` 출력 (Task 3), `error_log_core.aggregate` (Task 1)
-- Produces:
-  - `cluster_key(rec: dict) -> str` — message 의 숫자/경로 토큰을 정규화한 묶음 키
-  - `build_clusters(records: list[dict]) -> list[dict]` — `[{key, errorType, phase, agent, count, projects, sample}]` count 내림차순
-  - `render_report(*, records: list[dict], clusters: list[dict], stats: dict, generated_at: str) -> str`
-
-- [ ] **Step 1: 클러스터 테스트 작성 (실패하도록)**
-
-Append to `tests/inspect/test_okstra_error_zip.py`:
-
-```python
-def test_clusters_group_by_normalized_message():
-    records = [
-        {"errorType": "cli-failure", "phase": "impl", "agent": "codex-worker",
-         "message": "timeout after 124s", "sourceProject": "proj-1"},
-        {"errorType": "cli-failure", "phase": "impl", "agent": "codex-worker",
-         "message": "timeout after 999s", "sourceProject": "proj-2"},
-        {"errorType": "tool-failure", "phase": "impl", "agent": "claude-worker",
-         "message": "Edit denied", "sourceProject": "proj-1"},
-    ]
-    clusters = error_zip.build_clusters(records)
-    assert clusters[0]["count"] == 2                  # 두 timeout 이 한 클러스터
-    assert clusters[0]["errorType"] == "cli-failure"
-    assert set(clusters[0]["projects"]) == {"proj-1", "proj-2"}
-    assert any(c["errorType"] == "tool-failure" for c in clusters)
-
-
-def test_render_report_lists_clusters_and_unreachable():
-    records = [{"errorType": "cli-failure", "phase": "impl", "agent": "codex-worker",
-                "message": "timeout", "sourceProject": "proj-1", "source": "worker-reported"}]
-    clusters = error_zip.build_clusters(records)
-    md = error_zip.render_report(
-        records=records, clusters=clusters,
-        stats={"runCount": 1, "unreachableRuns": 2, "projectRoots": ["/x"]},
-        generated_at="2026-06-20T00:00:00+00:00",
-    )
-    assert "cli-failure" in md
-    assert "도달 불가" in md          # unreachableRuns 표면화
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py::test_clusters_group_by_normalized_message -v`
-Expected: FAIL — `AttributeError: ... has no attribute 'build_clusters'`
-
-- [ ] **Step 3: 클러스터 + 렌더 구현**
-
-Append to `scripts/okstra_ctl/error_zip.py` (상단 import 에 `import re`, `import datetime as dt` 추가):
-
-```python
-_NUM = re.compile(r"\d+")
-_PATHISH = re.compile(r"[/\\][^\s]+")
-
-
-def cluster_key(rec: dict) -> str:
-    msg = str(rec.get("message", ""))
-    msg = _PATHISH.sub("<path>", msg)
-    msg = _NUM.sub("<n>", msg)
-    msg = msg.strip()[:80]
-    return "|".join([
-        str(rec.get("errorType", "")),
-        str(rec.get("phase", "")),
-        str(rec.get("agent", "")),
-        msg,
-    ])
-
-
-def build_clusters(records: list[dict]) -> list[dict]:
-    buckets: dict[str, dict] = {}
-    for rec in records:
-        key = cluster_key(rec)
-        b = buckets.setdefault(key, {
-            "key": key, "errorType": str(rec.get("errorType", "")),
-            "phase": str(rec.get("phase", "")), "agent": str(rec.get("agent", "")),
-            "count": 0, "projects": set(), "sample": str(rec.get("message", "")),
-        })
-        b["count"] += 1
-        b["projects"].add(str(rec.get("sourceProject", "")))
-    clusters = []
-    for b in buckets.values():
-        b["projects"] = sorted(p for p in b["projects"] if p)
-        clusters.append(b)
-    clusters.sort(key=lambda c: (-c["count"], c["key"]))
-    return clusters
-
-
-def render_report(*, records, clusters, stats, generated_at) -> str:
-    agg = aggregate(records)
-    lines = [
-        "# okstra cross-project 에러 환류 리포트",
-        "",
-        f"- 생성 시각: {generated_at}",
-        f"- 총 에러: {agg['errorCount']} (로그 {stats['runCount']} run)",
-        f"- 도달 불가 run: {stats['unreachableRuns']}",
-        f"- errorType 분포: {agg['byErrorType']}",
-        "",
-        "## 빈발 클러스터 (brief 분할 단위)",
-        "",
-        "| # | errorType | phase | agent | count | projects | 대표 메시지 |",
-        "|---|---|---|---|---:|---|---|",
-    ]
-    for i, c in enumerate(clusters, start=1):
-        sample = c["sample"].replace("|", "\\|").replace("\n", " ")[:60]
-        lines.append(
-            f"| {i} | {c['errorType']} | {c['phase']} | {c['agent']} "
-            f"| {c['count']} | {len(c['projects'])} | {sample} |"
-        )
-    return "\n".join(lines) + "\n"
-```
-
-(`aggregate` 는 Task 1 코어에서 import — `from okstra_ctl.error_log_core import parse_records, aggregate` 로 import 줄 확장.)
-
-- [ ] **Step 4: 통과 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py -v`
-Expected: PASS (전체)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/error_zip.py tests/inspect/test_okstra_error_zip.py
-git commit -m "feat(inspect): error-zip 클러스터 집계 + 리포트 렌더(data-driven)"
-```
-
----
-
-### Task 5: zip 생성 + main(argparse --out) + 출력 경로 기억
-
-수집→익명화→집계→`.zip`(report.md + errors/anonymized.jsonl) 생성을 묶고, CLI 진입점을 만든다. 성공 시 `--out` 경로를 `~/.okstra/error-zip.json` 의 `lastOutputPath` 에 기억한다.
-
-**Files:**
-- Modify: `scripts/okstra_ctl/error_zip.py`
-- Test: `tests/inspect/test_okstra_error_zip.py`
-
-**Interfaces:**
-- Consumes: Task 2–4 함수, `okstra_ctl.paths.okstra_home`
-- Produces:
-  - `build_zip(home: Path, out_path: Path, now: dt.datetime) -> dict` — `{outPath, errorCount, runCount, unreachableRuns, clusterCount, projectCount}`
-  - `remember_output_path(home: Path, out_path: Path) -> None`
-  - `last_output_path(home: Path) -> str`
-  - `main(argv: list[str] | None = None) -> int`
-
-- [ ] **Step 1: zip + main 테스트 작성 (실패하도록)**
-
-Append to `tests/inspect/test_okstra_error_zip.py` (상단에 `import zipfile`, `import datetime as dt` 추가):
-
-```python
-def test_main_writes_zip_and_remembers_path(tmp_path, capsys):
-    home = okstra_home()
-    p1 = tmp_path / "proj1"
-    rel = ".okstra/tasks/g/DEV-1/runs/implementation"
-    _seed_project(p1, rel, [_rec(), _rec(errorType="tool-failure")])
-    append_jsonl(home / "recent.jsonl", _index_row(p1, rel))
-    out = tmp_path / "bundle.zip"
-
-    rc = error_zip.main(["--out", str(out)])
-    assert rc == 0
-    summary = json.loads(capsys.readouterr().out)
-    assert summary["errorCount"] == 2
-    assert out.is_file()
-    with zipfile.ZipFile(out) as zf:
-        names = zf.namelist()
-        assert "report.md" in names
-        assert any(n.startswith("errors/") for n in names)
-        report = zf.read("report.md").decode("utf-8")
-        assert "/proj1" not in report          # 익명화 확인
-    assert error_zip.last_output_path(home) == str(out)
-
-
-def test_main_no_errors_still_writes_zip(tmp_path, capsys):
-    out = tmp_path / "empty.zip"
-    rc = error_zip.main(["--out", str(out)])
-    assert rc == 0
-    summary = json.loads(capsys.readouterr().out)
-    assert summary["errorCount"] == 0
-    assert out.is_file()
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py::test_main_writes_zip_and_remembers_path -v`
-Expected: FAIL — `AttributeError: ... has no attribute 'main'`
-
-- [ ] **Step 3: zip + main + config 구현**
-
-Append to `scripts/okstra_ctl/error_zip.py` (상단 import 에 `import argparse`, `import json`, `import sys`, `import zipfile` 추가; `from okstra_ctl.paths import okstra_home` 추가):
-
-```python
-_CONFIG_NAME = "error-zip.json"
-
-
-def remember_output_path(home: Path, out_path: Path) -> None:
-    cfg = home / _CONFIG_NAME
-    cfg.write_text(
-        json.dumps({"lastOutputPath": str(out_path)}, ensure_ascii=False, indent=2),
-        encoding="utf-8",
-    )
-
-
-def last_output_path(home: Path) -> str:
-    cfg = home / _CONFIG_NAME
-    if not cfg.is_file():
-        return ""
-    try:
-        return str(json.loads(cfg.read_text(encoding="utf-8")).get("lastOutputPath", ""))
-    except Exception:
-        return ""
-
-
-def build_zip(home: Path, out_path: Path, now: dt.datetime) -> dict:
-    records, stats = collect_records(home)
-    clean, _ = anonymize(records)
-    clusters = build_clusters(clean)
-    report = render_report(
-        records=clean, clusters=clusters, stats=stats,
-        generated_at=now.isoformat(),
-    )
-    out_path.parent.mkdir(parents=True, exist_ok=True)
-    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as zf:
-        zf.writestr("report.md", report)
-        payload = "\n".join(json.dumps(r, ensure_ascii=False) for r in clean)
-        zf.writestr("errors/anonymized.jsonl", payload + ("\n" if payload else ""))
-    remember_output_path(home, out_path)
-    return {
-        "outPath": str(out_path),
-        "errorCount": len(clean),
-        "runCount": stats["runCount"],
-        "unreachableRuns": stats["unreachableRuns"],
-        "clusterCount": len(clusters),
-        "projectCount": len(stats["projectRoots"]),
-    }
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        prog="okstra error-zip",
-        description="cross-project okstra 에러를 수집·익명화해 zip 으로 묶는다.",
-    )
-    parser.add_argument("--out", required=True, help="출력 .zip 절대/상대 경로")
-    args = parser.parse_args(argv)
-    home = okstra_home()
-    result = build_zip(home, Path(args.out), dt.datetime.now(dt.timezone.utc))
-    print(json.dumps(result, ensure_ascii=False, indent=2))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main(sys.argv[1:]))
-```
-
-- [ ] **Step 4: 통과 확인 + 모듈 직접 실행 스모크**
-
-Run: `python3 -m pytest tests/inspect/test_okstra_error_zip.py -v`
-Expected: PASS (전체)
-
-Run: `OKSTRA_HOME=$(mktemp -d) python3 -m okstra_ctl.error_zip --out /tmp/ez-smoke.zip`
-Expected: stdout 에 `"errorCount": 0` JSON, `/tmp/ez-smoke.zip` 생성 (PYTHONPATH 에 `scripts/` 필요: `PYTHONPATH=scripts`)
-
-- [ ] **Step 5: 커밋**
-
-```bash
-git add scripts/okstra_ctl/error_zip.py tests/inspect/test_okstra_error_zip.py
-git commit -m "feat(inspect): error-zip zip 생성·CLI·출력경로 기억"
-```
-
----
-
-### Task 6: Node 래퍼 + cli-registry 등록
-
-`okstra error-zip --out <path>` 를 노출한다. error-report.mjs 를 복제해 module/USAGE 만 바꾼다.
-
-**Files:**
-- Create: `src/commands/inspect/error-zip.mjs`
-- Modify: `src/cli-registry.mjs` (error-report 객체 `:106-112` 바로 뒤)
-
-**Interfaces:**
-- Consumes: `okstra_ctl.error_zip` (Task 5), `src/lib/python-helper.mjs` 의 `runPythonModule`
-- Produces: `run(args) -> Promise<number>`
-
-- [ ] **Step 1: Node 래퍼 작성**
-
-Create `src/commands/inspect/error-zip.mjs`:
-
-```js
-import { runPythonModule } from "../../lib/python-helper.mjs";
-
-const USAGE = `okstra error-zip — bundle cross-project okstra error logs into a zip
-
-Usage:
-  okstra error-zip --out <path>
-
-Walks the global run-index (~/.okstra/recent.jsonl + active.jsonl), collects
-every target project's runs/*/logs/errors-*.jsonl, anonymizes records, and
-writes a .zip (report.md + errors/anonymized.jsonl) to <path>. Read-only
-against every target's .okstra/. Prints a JSON summary to stdout.
-`;
-
-export async function run(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(USAGE);
-    return 0;
-  }
-  const result = await runPythonModule({
-    module: "okstra_ctl.error_zip",
-    args,
-    stdio: "inherit-stdout",
-  });
-  return result.code ?? 0;
-}
-```
-
-- [ ] **Step 2: cli-registry 등록**
-
-In `src/cli-registry.mjs`, `error-report` 객체 바로 뒤에 추가:
-
-```js
-  {
-    name: "error-zip",
-    module: "./commands/inspect/error-zip.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Bundle cross-project okstra error logs into a zip"],
-  },
-```
-
-- [ ] **Step 3: CLI 스모크 테스트**
-
-Run: `node bin/okstra error-zip --help`
-Expected: USAGE 텍스트 출력, 종료코드 0
-
-Run: `OKSTRA_HOME=$(mktemp -d) node bin/okstra error-zip --out /tmp/ez-node.zip`
-Expected: JSON 요약(`"errorCount": 0`), `/tmp/ez-node.zip` 생성
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add src/commands/inspect/error-zip.mjs src/cli-registry.mjs
-git commit -m "feat(cli): okstra error-zip facet Node 래퍼 + 레지스트리 등록"
-```
-
----
-
-### Task 7: okstra-inspect SKILL 에 error-zip facet + 저장경로 picker
-
-읽기측 facet 으로 노출하고, 출력 경로를 이전값 재사용/직접입력 3-옵션 picker 로 받는다.
-
-**Files:**
-- Modify: `skills/okstra-inspect/SKILL.md` (3곳: frontmatter description `:4`, sub-command 테이블 `:19` 뒤, 본문 `## recap` `:764` 앞)
-
-**Interfaces:** 없음 (마크다운). CLI 호출은 `okstra error-zip --out <chosen>`.
-
-- [ ] **Step 1: 트리거 + 테이블 행 추가**
-
-In `skills/okstra-inspect/SKILL.md` frontmatter `description`(`:4`), 트리거 추가: `"okstra error-zip", "에러 zip", "에러 환류", "에러 번들", "cross-project 에러"`. facet 개수 문장(`:9` 부근의 `eight facets` / `status...recap` 나열)을 9개로 갱신.
-
-Sub-command 테이블(`:19` `errors` 행 뒤)에 추가:
-
-```
-| `error-zip` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
-```
-
-- [ ] **Step 2: `## error-zip` 본문 섹션 추가**
-
-`## recap`(`:764`) 직전에 `---` 구분선과 함께 삽입:
-
-````markdown
-## error-zip
-
-Trigger phrases: "okstra error-zip", "에러 zip", "에러 환류", "에러 번들", "cross-project 에러".
-
-머신 내 모든 타겟 프로젝트의 okstra 실행 에러(`runs/*/logs/errors-*.jsonl`)를 글로벌 run-index 로 수집·익명화해 `.zip`(집계 리포트 + 익명화 JSONL)으로 묶는다. 모든 타겟의 `.okstra/` 에 대해 read-only.
-
-### error-zip.1 — 출력 경로 결정 (picker)
-
-이전 출력 경로를 `~/.okstra/error-zip.json` 의 `lastOutputPath` 에서 읽는다. 그 값이 있으면 3-옵션 picker 로 제시:
-
-1. (이전 경로 있음) `<lastOutputPath>` 재사용 — 추천, 첫 옵션.
-   (이전 경로 없음) 기본 경로 `~/okstra-error-feedback-<YYYY-MM-DD>.zip` 제안 — 추천.
-2. 직접 입력 (항상 마지막 옵션).
-
-`~/.okstra/error-zip.json` 읽기는 Read 로 직접 수행한다(없으면 이전 경로 없음으로 간주).
-
-### error-zip.2 — 렌더 실행
-
-```bash
-okstra error-zip --out <결정된 경로>
-```
-
-### error-zip.3 — 요약 보고
-
-stdout JSON 을 파싱해 보고:
-
-| 필드 | 출처 |
-|---|---|
-| 출력 zip | `outPath` |
-| 총 에러 | `errorCount` |
-| 로그(run) | `runCount` |
-| 도달 불가 run | `unreachableRuns` |
-| 클러스터 수 | `clusterCount` |
-| 프로젝트 수 | `projectCount` |
-
-- `unreachableRuns > 0` 이면 표면화한다(침묵 누락 금지).
-- 끝에 다음 단계를 안내한다: "이 zip 으로 okstra 자신을 고치려면 `/okstra-brief` 의 error-feedback variant 로 brief 를 만든 뒤 `okstra-run --task-type error-analysis` 를 okstra 레포에서 실행하세요."
-````
-
-- [ ] **Step 3: 일관성 grep**
-
-Run: `grep -n "error-zip" skills/okstra-inspect/SKILL.md`
-Expected: description / 테이블 행 / 본문 섹션 3곳에 등장. facet 개수 문장이 9로 갱신됐는지 육안 확인.
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add skills/okstra-inspect/SKILL.md
-git commit -m "feat(inspect): okstra-inspect 에 error-zip facet + 저장경로 picker 추가"
-```
-
----
-
-### Task 8: okstra-brief 에 error-feedback variant 추가
-
-zip 을 입력받아 빈발 클러스터 1개를 error-analysis brief 로 변환하는 variant 를 추가한다.
-
-**Files:**
-- Modify: `skills/okstra-brief/SKILL.md`
-
-**Interfaces:** 없음 (마크다운). 출력은 error-analysis brief 파일.
-
-- [ ] **Step 1: 기존 variant 등록 지점 확인**
-
-Run: `grep -n "variant\|Codebase scan\|codebase-scan\|Step 1" skills/okstra-brief/SKILL.md | head -40`
-Expected: variant 선택 메뉴(Step 1)와 codebase-scan variant 정의 위치 파악. error-feedback variant 를 같은 메뉴/패턴에 추가.
-
-- [ ] **Step 2: variant 메뉴에 error-feedback 추가**
-
-variant 선택 Step(Codebase scan 이 등록된 곳과 같은 목록)에 `error-feedback` 옵션을 추가하고, 별도 variant 섹션을 작성:
-
-````markdown
-### variant: error-feedback (okstra 자가수정용)
-
-입력: `okstra error-zip` 이 만든 `.zip`. 사용자에게 zip 경로를 묻는다(이전 경로 picker 가 있으면 재사용 제안).
-
-1. zip 의 `report.md` 를 읽어 빈발 클러스터 표를 사용자에게 보여주고, **클러스터 1개**를 고르게 한다. (3-옵션: top-1 클러스터 추천 / top-2 / 직접 지정)
-2. 고른 클러스터의 익명화 레코드(`errors/anonymized.jsonl` 에서 해당 errorType+phase+agent 일치분)를 brief 의 `Source Material` 에 인용한다 — errorType·command·exitCode·phase·agent·대표 메시지.
-3. brief frontmatter 의 task-type 은 `error-analysis`, 수정 대상은 **okstra 레포 자신**임을 본문에 명시한다("이 에러는 okstra 런타임/프롬프트/래퍼/권한 seed 결함 신호이며, 수정 대상은 okstra 소스(`prompts/`·`agents/`·`scripts/`·`templates/`)").
-4. **단일 클러스터 = 단일 실패조건** 원칙을 지킨다 — 이질적 errorType 을 한 brief 에 섞지 않는다(error-analysis 의 symptom-lock 요건).
-5. 생성된 brief 끝에 다음 단계를 인라인으로 적는다: "okstra 레포에서 `okstra-run --task-type error-analysis` 로 이 brief 를 실행하세요."
-````
-
-- [ ] **Step 3: 일관성 grep**
-
-Run: `grep -n "error-feedback\|error-zip" skills/okstra-brief/SKILL.md`
-Expected: variant 메뉴 + variant 섹션에 등장.
-
-- [ ] **Step 4: 커밋**
-
-```bash
-git add skills/okstra-brief/SKILL.md
-git commit -m "feat(brief): okstra-brief 에 error-feedback variant(zip→error-analysis brief) 추가"
-```
-
----
-
-### Task 9: 빌드 동기화 + 전체 검증
-
-소스 변경을 `runtime/` 으로 동기화하고 전체 스위트를 돌린다.
-
-**Files:** 없음 (빌드/검증)
-
-- [ ] **Step 1: 빌드**
-
-Run: `npm run build`
-Expected: 성공. `runtime/python/okstra_ctl/error_zip.py`, `error_log_core.py` 가 생성되고 skills 가 동기화됨.
-
-- [ ] **Step 2: 빌드 산출물 동기화 확인**
-
-Run: `diff -q scripts/okstra_ctl/error_zip.py runtime/python/okstra_ctl/error_zip.py && diff -q scripts/okstra_ctl/error_log_core.py runtime/python/okstra_ctl/error_log_core.py`
-Expected: 차이 없음(빌드가 정확히 복사). 차이 있으면 빌드 설정에 신규 모듈 누락 — `tools/build.mjs` 확인.
-
-- [ ] **Step 3: 전체 unit suite**
-
-Run: `python3 -m pytest tests/`
-Expected: PASS (기존 + 신규 전부)
-
-- [ ] **Step 4: facet 디스패치 스모크**
-
-Run: `node bin/okstra doctor`
-Expected: 런타임/스킬 진단 통과.
-
-Run: `node bin/okstra --help | grep error-zip`
-Expected: error-zip 이 introspection 카테고리에 노출.
-
-- [ ] **Step 5: CHANGES.md 항목 추가**
-
-`CHANGES.md` 에 사용자 영향 항목 추가(한국어):
-
-```markdown
-- `okstra error-zip` facet 추가: 머신 내 모든 타겟 프로젝트의 okstra 실행 에러를 cross-project 로 수집·익명화해 zip 으로 묶고, `okstra-brief` 의 error-feedback variant 로 okstra 자신을 고치는 error-analysis brief 를 만들 수 있습니다.
-  - 사용자 영향: 여러 프로젝트에 흩어진 okstra 결함 신호를 한데 모아 okstra 자가수정 lifecycle 로 환류할 수 있습니다.
-```
-
-- [ ] **Step 6: 최종 커밋**
-
-```bash
-git add runtime/ CHANGES.md
-git commit -m "build: error-zip/error-feedback 런타임 동기화 + CHANGES 기록"
-```
-
----
-
-## Self-Review 메모
-
-- **Spec coverage**: spec §4(okstra-error-zip)→Task 2–7, §4.4 익명화→Task 3, §4.5 코어 공유→Task 1, §4.6 저장 UX/경로 기억→Task 5·7, §5(brief variant)→Task 8, §6(lifecycle 재사용)→신규 구현 없음(브리프가 error-analysis 로 라우팅), §2 errorType 비결합→Task 1·3·4 전반, §8.1–8.3 열린 디테일→Task 3(allowlist)·Task 5(config 파일명 `error-zip.json`)·Task 4(클러스터 기준).
-- **수정 lifecycle(error-analysis→implementation)** 은 기존 기능이라 plan 에 구현 task 없음 — Task 8 의 brief 가 진입점을 만든다.
-- **`append_jsonl` 시그니처**는 Task 2 Step 4 에서 실제값으로 검증 후 맞춘다(가정: `append_jsonl(path, row)`).
-- **빌드가 신규 모듈을 자동 포함하는지**는 Task 9 Step 2 에서 검증 — 누락 시 `tools/build.mjs` 수정 필요.