okstra 0.102.2 → 0.102.4

package/docs/superpowers/plans/2026-06-17-okstra-error-report.md

@@ -1,724 +0,0 @@
-# okstra-run 에러 집계 리포트 구현 Plan
-
-> **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-run 이 적재한 `errors-<type>-<seq>.jsonl` 을 task 단위로 집계해 timestamp 누적 `.md` 리포트로 렌더하는 신규 CLI `okstra error-report` 와, 그것을 호출하는 okstra-inspect `errors` facet 을 추가한다.
-
-**Architecture:** Python 렌더러(`okstra_ctl/error_report.py`)가 결정론적으로 errors.jsonl 들을 glob·집계·렌더하고 stdout 으로 요약 JSON 을 낸다. Node CLI 래퍼(`src/error-report.mjs`)가 이를 `okstra error-report` 로 노출하고, inspect `errors` facet 이 호출 결과를 표시한다. task-key→task-root 해석은 `context_cost.py` 에서 공유 헬퍼(`task_target.py`)로 추출해 두 소비자가 공유한다.
-
-**Tech Stack:** Python 3 (argparse, json, pathlib, datetime), Node ES modules, pytest.
-
-설계 근거: [`docs/superpowers/specs/2026-06-17-okstra-error-report-design.md`](../specs/2026-06-17-okstra-error-report-design.md)
-
----
-
-## File Structure
-
-- Create: `scripts/okstra_ctl/task_target.py` — task-key → (task_root, project_root) 해석 공유 헬퍼. `context_cost.py` 의 private 헬퍼를 추출한 SSOT.
-- Modify: `scripts/okstra_ctl/context_cost.py` — 추출한 헬퍼를 `task_target` 에서 import (중복 제거).
-- Create: `scripts/okstra_ctl/error_report.py` — glob·parse·aggregate·render·main.
-- Create: `tests/test_okstra_error_report.py` — 집계/파싱/렌더/main 단위 테스트.
-- Create: `src/error-report.mjs` — Node CLI 래퍼 (`context-cost.mjs` 복제).
-- Modify: `src/cli-registry.mjs` — `error-report` 명령 등록.
-- Modify: `skills/okstra-inspect/SKILL.md` — `errors` facet 섹션 + dispatch 행 + 정체성 문구.
-- Modify: `CHANGES.md` — 사용자 영향 항목.
-
----
-
-## Task 1: task-key 해석 공유 헬퍼 추출
-
-기존 `context_cost.py` 가 두 번째 소비자(`error_report.py`)를 갖게 되므로, task-key 해석 로직을 공유 모듈로 추출한다(single-reference-point). 동작은 바뀌지 않으므로 기존 cost 테스트가 회귀 가드 역할을 한다.
-
-**Files:**
-- Create: `scripts/okstra_ctl/task_target.py`
-- Modify: `scripts/okstra_ctl/context_cost.py:16`, `:92-123`
-
-- [ ] **Step 1: 공유 헬퍼 파일 작성**
-
-Create `scripts/okstra_ctl/task_target.py` (코드는 `context_cost.py:92-123` 에서 그대로 이동, 이름에서 선행 `_` 제거):
-
-```python
-"""task-key → (task_root, project_root) 해석 공유 헬퍼.
-
-read-side CLI(context-cost, error-report)가 동일한 입력 계약을 공유하기 위한
-SSOT. target 은 task-root 경로 / task-key 둘 다 받는다.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-from okstra_project import ResolverError, find_task_root, resolve_project_root
-
-
-def resolve_task_root(target: str, project_root: str, cwd: str) -> tuple[Path, Path]:
-    target_path = Path(target).expanduser()
-    if target_path.exists():
-        task_root = target_path.resolve()
-        return task_root, infer_project_root(task_root)
-
-    try:
-        resolved_project = Path(
-            resolve_project_root(explicit_root=project_root, cwd=cwd)
-        ).resolve()
-    except ResolverError as exc:
-        raise SystemExit(f"project root resolution failed: {exc}") from exc
-
-    task_root = find_task_root(resolved_project, target)
-    if task_root is None:
-        raise SystemExit(f"no task root for task key: {target}")
-    return task_root.resolve(), resolved_project
-
-
-def infer_project_root(task_root: Path) -> Path:
-    parts = task_root.parts
-    if ".okstra" not in parts:
-        return task_root
-    idx = parts.index(".okstra")
-    return Path(*parts[:idx]).resolve()
-
-
-def project_rel(path: Path, project_root: Path) -> str:
-    try:
-        return str(path.resolve().relative_to(project_root.resolve()))
-    except ValueError:
-        return str(path)
-```
-
-- [ ] **Step 2: context_cost.py 가 공유 헬퍼를 import 하도록 변경**
-
-In `scripts/okstra_ctl/context_cost.py`, line 16 의 import 아래에 추가하고, `_resolve_task_root`/`_infer_project_root`/`_project_rel` 정의(line 92-123)를 삭제:
-
-```python
-from okstra_project import ResolverError, find_task_root, resolve_project_root
-from okstra_ctl.task_target import resolve_task_root, infer_project_root, project_rel
-```
-
-그런 다음 파일 전체에서 호출부를 치환:
-- `_resolve_task_root(` → `resolve_task_root(`
-- `_infer_project_root(` → `infer_project_root(`
-- `_project_rel(` → `project_rel(`
-
-치환 명령:
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-sed -i '' 's/_resolve_task_root(/resolve_task_root(/g; s/_infer_project_root(/infer_project_root(/g; s/_project_rel(/project_rel(/g' scripts/okstra_ctl/context_cost.py
-```
-
-이후 `context_cost.py` 안에 남은 `def resolve_task_root`/`def infer_project_root`/`def project_rel` 정의(이전 `_` 버전)를 수동으로 삭제한다. `okstra_project import ...` 줄 다음에 더 이상 `ResolverError`/`find_task_root`/`resolve_project_root` 를 직접 쓰지 않으면 그 import 도 제거한다(grep 으로 확인 후).
-
-- [ ] **Step 3: cost 회귀 테스트 통과 확인**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/ -k "context_cost or cost" -q`
-Expected: PASS (전부). 만약 import 오류면 Step 2 의 남은 정의/직접 사용처를 점검.
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add scripts/okstra_ctl/task_target.py scripts/okstra_ctl/context_cost.py
-git commit -m "refactor(ctl): task-key 해석 헬퍼를 task_target 공유 모듈로 추출"
-```
-
----
-
-## Task 2: error_report.py 집계 코어 (glob + parse + aggregate)
-
-errors.jsonl 을 찾아 파싱하고 집계하는 순수 함수들. project_root 없이 task_root 만으로 단위 테스트 가능하게 설계한다.
-
-**Files:**
-- Create: `scripts/okstra_ctl/error_report.py`
-- Test: `tests/test_okstra_error_report.py`
-
-- [ ] **Step 1: 실패 테스트 작성 (glob + parse + aggregate)**
-
-Create `tests/test_okstra_error_report.py`:
-
-```python
-import json
-from pathlib import Path
-
-from okstra_ctl import error_report
-
-
-def _write_log(task_root: Path, run_seg: str, seq: str, records: list[dict]) -> None:
-    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")
-
-
-def _rec(**over) -> dict:
-    base = {
-        "ts": "2026-06-17T01:00:00+00:00",
-        "taskKey": "p: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 test_glob_finds_flat_and_staged(tmp_path):
-    _write_log(tmp_path, "implementation", "001", [_rec()])
-    _write_log(tmp_path, "implementation/stage-2", "003", [_rec(phase="phase-2")])
-    paths = error_report._glob_error_logs(tmp_path)
-    assert len(paths) == 2
-
-
-def test_parse_skips_blank_and_broken_lines(tmp_path):
-    log_dir = tmp_path / "runs" / "implementation" / "logs"
-    log_dir.mkdir(parents=True)
-    (log_dir / "errors-implementation-001.jsonl").write_text(
-        json.dumps(_rec()) + "\n\n" + "{not json\n" + "[1,2]\n",
-        encoding="utf-8",
-    )
-    records, skipped = error_report._parse_records(
-        [log_dir / "errors-implementation-001.jsonl"]
-    )
-    assert len(records) == 1
-    assert skipped == 2  # broken json line + non-dict array
-
-
-def test_aggregate_counts(tmp_path):
-    records = [
-        _rec(errorType="cli-failure", source="worker-reported",
-             phase="implementation", agent="claude-worker"),
-        _rec(errorType="tool-failure", source="lead-observed",
-             phase="implementation", agent="claude-lead"),
-        _rec(errorType="cli-failure", source="worker-reported",
-             phase="error-analysis", agent="codex-worker"),
-    ]
-    agg = error_report._aggregate(records)
-    assert agg["errorCount"] == 3
-    assert agg["byErrorType"]["cli-failure"] == 2
-    assert agg["bySource"]["lead-observed"] == 1
-    assert {row["phase"]: row["count"] for row in agg["byPhase"]} == {
-        "implementation": 2, "error-analysis": 1,
-    }
-    assert {row["agent"]: row["count"] for row in agg["byAgent"]}["codex-worker"] == 1
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_error_report.py -q`
-Expected: FAIL — `ModuleNotFoundError: No module named 'okstra_ctl.error_report'` (또는 AttributeError).
-
-- [ ] **Step 3: 집계 코어 구현**
-
-Create `scripts/okstra_ctl/error_report.py`:
-
-```python
-"""Read-side aggregator for okstra-run error logs.
-
-task 의 모든 run errors-<type>-<seq>.jsonl 을 모아 phase / worker / errorType
-별로 집계하고 timestamp 누적 .md 리포트로 렌더한다. task 산출물을 mutate 하지
-않는다.
-"""
-from __future__ import annotations
-
-import argparse
-import datetime as dt
-import json
-import sys
-from pathlib import Path
-
-from okstra_ctl.task_target import resolve_task_root, project_rel
-
-
-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:
-        out[str(rec.get(key, ""))] = out.get(str(rec.get(key, "")), 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: 통과 확인**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_error_report.py -q`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add scripts/okstra_ctl/error_report.py tests/test_okstra_error_report.py
-git commit -m "feat(ctl): error_report 집계 코어(glob/parse/aggregate)"
-```
-
----
-
-## Task 3: 렌더(.md) + main(stdout JSON)
-
-집계 결과를 `.md` 로 렌더하고, main 이 파일을 쓰고 stdout JSON 요약을 낸다.
-
-**Files:**
-- Modify: `scripts/okstra_ctl/error_report.py`
-- Test: `tests/test_okstra_error_report.py`
-
-- [ ] **Step 1: 실패 테스트 추가**
-
-Append to `tests/test_okstra_error_report.py`:
-
-```python
-def test_render_markdown_has_sections(tmp_path):
-    records = [_rec(stderrExcerpt="line1\nline2")]
-    md = error_report.render_markdown(
-        task_key="p:g:DEV-1",
-        records=records,
-        agg=error_report._aggregate(records),
-        parse_skipped=0,
-        generated_at="2026-06-17T02:00:00+00:00",
-    )
-    assert "# okstra 에러 리포트" in md
-    assert "## 요약" in md
-    assert "## phase 별 집계" in md
-    assert "## worker(agent) 별 집계" in md
-    assert "## 개별 에러 이벤트" in md
-
-
-def test_main_writes_md_and_prints_json(tmp_path, capsys):
-    task_root = tmp_path / ".okstra" / "tasks" / "g" / "DEV-1"
-    _write_log(task_root, "implementation", "001", [_rec()])
-    (task_root / "task-manifest.json").write_text(
-        json.dumps({"taskKey": "p:g:DEV-1"}), encoding="utf-8"
-    )
-    rc = error_report.main([str(task_root)])
-    assert rc == 0
-    out = json.loads(capsys.readouterr().out)
-    assert out["totals"]["errorCount"] == 1
-    report_abs = tmp_path / out["reportPath"]
-    assert report_abs.is_file()
-    assert "## 개별 에러 이벤트" in report_abs.read_text(encoding="utf-8")
-
-
-def test_main_no_logs_reports_zero(tmp_path, capsys):
-    task_root = tmp_path / ".okstra" / "tasks" / "g" / "DEV-2"
-    task_root.mkdir(parents=True)
-    (task_root / "task-manifest.json").write_text(
-        json.dumps({"taskKey": "p:g:DEV-2"}), encoding="utf-8"
-    )
-    rc = error_report.main([str(task_root)])
-    assert rc == 0
-    out = json.loads(capsys.readouterr().out)
-    assert out["totals"]["errorCount"] == 0
-    assert out["reportPath"] == ""  # glob 0개 → .md 미생성
-```
-
-- [ ] **Step 2: 실패 확인**
-
-Run: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_error_report.py -q`
-Expected: FAIL — `AttributeError: module 'okstra_ctl.error_report' has no attribute 'render_markdown'`.
-
-- [ ] **Step 3: 렌더 + main 구현 (error_report.py 끝에 추가)**
-
-```python
-def _md_table(header: list[str], rows: list[list[str]]) -> str:
-    line = "| " + " | ".join(header) + " |"
-    sep = "| " + " | ".join("---" for _ in header) + " |"
-    body = ["| " + " | ".join(cells) + " |" for cells in rows]
-    return "\n".join([line, sep, *body]) if rows else line + "\n" + sep + "\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 "_없음_"
-    parts = [
-        f"# okstra 에러 리포트 — {task_key}",
-        "",
-        "## 요약",
-        "",
-        f"- 총 에러: {agg['errorCount']}건",
-        f"- 집계된 로그(run) 수: {agg['runCount']}",
-        f"- errorType 별: {by_type}",
-        f"- source 별: {by_src}",
-        f"- 파싱 건너뛴 줄: {parse_skipped}",
-        f"- 생성 시각: {generated_at}",
-        "",
-        "## phase 별 집계",
-        "",
-        _md_table(["Phase", "Count"],
-                  [[r["phase"] or "(없음)", str(r["count"])] for r in agg["byPhase"]]),
-        "",
-        "## worker(agent) 별 집계",
-        "",
-        _md_table(["Agent", "Count"],
-                  [[r["agent"] or "(없음)", str(r["count"])] for r in agg["byAgent"]]),
-        "",
-        "## 개별 에러 이벤트",
-        "",
-        _md_table(
-            ["ts", "phase", "agent", "errorType", "command", "exitCode", "message"],
-            [[
-                str(r.get("ts", "")), str(r.get("phase", "")), str(r.get("agent", "")),
-                str(r.get("errorType", "")), f"`{r.get('command', '')}`",
-                str(r.get("exitCode", "")),
-                str(r.get("message", "")).replace("|", "\\|").replace("\n", " "),
-            ] for r in sorted(records, key=lambda x: str(x.get("ts", "")))],
-        ),
-        "",
-    ]
-    return "\n".join(parts)
-
-
-def _timestamp_segment(now: dt.datetime) -> str:
-    return now.strftime("%Y-%m-%d_%H-%M-%S")
-
-
-def build_and_write(task_root: Path, project_root: Path, now: dt.datetime) -> dict:
-    manifest_path = task_root / "task-manifest.json"
-    task_key = ""
-    if manifest_path.is_file():
-        try:
-            task_key = json.loads(manifest_path.read_text(encoding="utf-8")).get("taskKey", "")
-        except Exception:
-            task_key = ""
-    paths = _glob_error_logs(task_root)
-    records, skipped = _parse_records(paths)
-    agg = _aggregate(records)
-    report_rel = ""
-    if paths:
-        md = render_markdown(
-            task_key=task_key, records=records, agg=agg,
-            parse_skipped=skipped, generated_at=now.isoformat(),
-        )
-        out_dir = task_root / "error-reports"
-        out_dir.mkdir(parents=True, exist_ok=True)
-        out_path = out_dir / f"error-report-{_timestamp_segment(now)}.md"
-        out_path.write_text(md, encoding="utf-8")
-        report_rel = project_rel(out_path, project_root)
-    return {
-        "taskKey": task_key,
-        "reportPath": report_rel,
-        "parseSkipped": skipped,
-        "totals": {
-            "errorCount": agg["errorCount"],
-            "runCount": agg["runCount"],
-            "byErrorType": agg["byErrorType"],
-            "bySource": agg["bySource"],
-        },
-        "byPhase": agg["byPhase"],
-        "byAgent": agg["byAgent"],
-    }
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(
-        description="Aggregate okstra-run error logs into a task-level report."
-    )
-    parser.add_argument("target", help="task root path or task-key")
-    parser.add_argument("--project-root", default="", help="project root for task-key lookup")
-    parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
-    args = parser.parse_args(argv)
-
-    task_root, project_root = resolve_task_root(args.target, args.project_root, args.cwd)
-    result = build_and_write(task_root, project_root, 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: `cd /Volumes/Workspaces/workspace/projects/Okstra && python3 -m pytest tests/test_okstra_error_report.py -q`
-Expected: PASS (6 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add scripts/okstra_ctl/error_report.py tests/test_okstra_error_report.py
-git commit -m "feat(ctl): error_report 렌더(.md) + main(stdout JSON)"
-```
-
----
-
-## Task 4: Node CLI 래퍼 + 레지스트리 등록
-
-`okstra error-report` 를 노출한다. `context-cost.mjs` 를 복제한다.
-
-**Files:**
-- Create: `src/error-report.mjs`
-- Modify: `src/cli-registry.mjs:100-105` (context-cost 항목 바로 뒤)
-
-- [ ] **Step 1: Node 래퍼 작성**
-
-Create `src/error-report.mjs`:
-
-```javascript
-import { runPythonModule } from "./_python-helper.mjs";
-
-const USAGE = `okstra error-report — aggregate okstra-run error logs into a task report
-
-Usage:
-  okstra error-report <task-root>
-  okstra error-report <task-key> --project-root <dir>
-  okstra error-report <task-key> --cwd <dir>
-
-Writes a timestamped markdown report under <task-root>/error-reports/ and
-prints a JSON summary (counts by errorType / source / phase / agent) to stdout.
-This is read-only against task state; it never mutates task artifacts.
-`;
-
-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_report",
-    args,
-    stdio: "inherit-stdout",
-  });
-  return result.code ?? 0;
-}
-```
-
-- [ ] **Step 2: 레지스트리 등록**
-
-In `src/cli-registry.mjs`, context-cost 항목(line 100-105) 바로 뒤에 추가:
-
-```javascript
-  {
-    name: "error-report",
-    module: "./error-report.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Aggregate okstra-run error logs into a task-level report"],
-  },
-```
-
-- [ ] **Step 3: 빌드 + smoke 테스트**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-npm run build
-node bin/okstra error-report --help
-```
-Expected: USAGE 출력, exit 0.
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add src/error-report.mjs src/cli-registry.mjs
-git commit -m "feat(cli): okstra error-report 명령 등록"
-```
-
----
-
-## Task 5: inspect `errors` facet + 정체성 문구
-
-okstra-inspect SKILL 에 facet 을 추가한다.
-
-**Files:**
-- Modify: `skills/okstra-inspect/SKILL.md` (frontmatter description, line 9 정체성, line 11-18 dispatch 표, 신규 `## errors` 섹션)
-
-- [ ] **Step 1: 정체성 문구 + dispatch 표 갱신**
-
-`skills/okstra-inspect/SKILL.md:9` 의 정체성 문장을 다음으로 교체:
-
-```
-Single read-side entry point for okstra runtime inspection plus the one status mutation that belongs here (`workStatus`) and read-derived artifact rendering (`errors` report). Sub-commands:
-```
-
-`SKILL.md:11-18` dispatch 표의 `cost` 행 다음에 추가:
-
-```
-| `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
-```
-
-frontmatter `description`(line 4) 의 trigger 목록 끝에 추가: `"okstra errors", "error report", "에러 리포트", "에러 보고", "에러 모아줘", "실패 로그 정리"`.
-
-- [ ] **Step 2: `## errors` facet 섹션 추가 (`## logs` 섹션 뒤, `## Output Rules (shared)` 앞)**
-
-```markdown
----
-
-## errors
-
-Trigger phrases: "okstra errors", "error report", "에러 리포트", "에러 보고", "에러 모아줘", "실패 로그 정리".
-
-Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-observed + worker-reported) into a timestamped markdown report and summarize it. This sub-command renders a **read-derived artifact** (a `.md` file) but never mutates task state (`task-manifest.json`, catalog, timeline).
-
-### errors.1 — Resolve target
-
-Accepted target forms (same as `cost`):
-
-1. Full task-key: `<project-id>:<task-group>:<task-id>`.
-2. Task id only — read `.okstra/discovery/task-catalog.json`, match `taskId` case-insensitively (multiple → list and ask; none → report not found).
-3. Task root path.
-
-### errors.2 — Run the renderer
-
-Use the CLI output as the source of truth:
-
-```bash
-okstra error-report <resolved-target> --project-root <projectRoot>
-```
-
-For a task-root path, run `okstra error-report <path>` directly. Do not parse the jsonl files by hand unless the CLI fails and the user explicitly asks for a manual fallback.
-
-### errors.3 — Summarize output
-
-Parse the stdout JSON and report:
-
-| Field | Source |
-|---|---|
-| Report file | `reportPath` (project-root-relative `.md`) |
-| Total errors | `totals.errorCount` |
-| Logs (runs) | `totals.runCount` |
-| By errorType | `totals.byErrorType` (tool-failure / cli-failure / contract-violation) |
-| By source | `totals.bySource` (lead-observed / worker-reported) |
-| By phase | `byPhase[]` |
-| By agent | `byAgent[]` |
-| Parse-skipped lines | `parseSkipped` |
-
-- If `reportPath` is empty AND `totals.errorCount == 0`: report `이 task 에는 기록된 에러 로그가 없습니다.` and do not claim a file was written.
-- Otherwise show the `.md` path and offer to read it.
-- If `parseSkipped > 0`, surface it (do not silently hide malformed lines).
-
-### errors — Output template
-
-```markdown
-## okstra Error Report — <task-key>
-
-- Report: `<reportPath-or-->`
-- Total errors: <N> across <runCount> log(s)
-- By type: <tool-failure: a, cli-failure: b, ...>
-- By source: <lead-observed: x, worker-reported: y>
-
-| Phase | Count |
-|---|---:|
-| implementation | 3 |
-
-| Agent | Count |
-|---|---:|
-| codex-worker | 2 |
-
-<If parseSkipped > 0: "⚠ 파싱 건너뛴 줄: <N>">
-```
-```
-
-- [ ] **Step 3: 빌드 + 동기화 확인**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-npm run build
-grep -c "## errors" runtime/skills/okstra-inspect/SKILL.md
-```
-Expected: `1` (runtime 에 동기화됨).
-
-- [ ] **Step 4: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add skills/okstra-inspect/SKILL.md
-git commit -m "feat(inspect): errors facet 추가 (error-report 호출 + 요약)"
-```
-
----
-
-## Task 6: CHANGES.md + 전체 회귀
-
-**Files:**
-- Modify: `CHANGES.md`
-
-- [ ] **Step 1: CHANGES.md 항목 추가**
-
-`CHANGES.md` 의 `## 2026-06-17` 섹션 안, 기존 첫 `###` 항목 앞에 추가:
-
-```markdown
-### feat(inspect): okstra-run 에러를 task 단위로 집계하는 error-report + errors facet
-
-- **배경**: okstra-run 은 실행 중 에러를 `runs/<task-type>/logs/errors-<type>-<seq>.jsonl` 에 구조화해 적재하지만(lead-observed + worker-reported), 그것을 읽어 사람에게 보고하는 기능이 없어 `latestRunStatus == error` 라는 run 단위 거친 상태만 확인 가능했다.
-- **해결**: task 의 모든 run errors.jsonl 을 phase/worker/errorType 별로 집계해 `<task_root>/error-reports/error-report-<timestamp>.md` 로 렌더하는 신규 CLI `okstra error-report` 와, 그것을 호출·요약하는 okstra-inspect `errors` facet 을 추가했다. task-key 해석은 `context_cost` 와 공유 헬퍼(`task_target`)로 통일했다.
-- 사용자 영향: `/okstra-inspect errors <task-key>` 또는 "에러 리포트" 로 특정 task 의 실행 에러를 집계한 markdown 리포트를 생성·요약받을 수 있다. 리포트는 timestamp 누적이라 이력이 보존된다.
-```
-
-- [ ] **Step 2: 전체 테스트 + 빌드**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-python3 -m pytest tests/ -q && npm run build && node bin/okstra --version
-```
-Expected: 전체 PASS, 빌드 done, 버전 출력.
-
-- [ ] **Step 3: Commit**
-
-```bash
-cd /Volumes/Workspaces/workspace/projects/Okstra
-git add CHANGES.md
-git commit -m "docs(changes): error-report + errors facet 사용자 영향 기록"
-```
-
----
-
-## Self-Review 결과 (작성자 점검)
-
-- **Spec coverage:** §3 아키텍처 4컴포넌트 → Task 1(task_target 추출은 §3 단일 참조점)·2·3(error_report)·4(mjs+registry)·5(SKILL). §4 CLI 인터페이스 → Task 3 main + Task 4 USAGE. §5 산출물 위치/구조 → Task 3 `build_and_write`(error-reports/ + timestamp) + `render_markdown`(5섹션). §6 glob(flat+staged) → Task 2 `_glob_error_logs`. §7 write 경계 문구 → Task 5 Step 1. §8 엣지케이스(0개/0건/깨진 줄) → Task 3 `test_main_no_logs`/Task 2 `test_parse_skips`. §9 테스트 → Task 2·3. 모든 spec 항목에 대응 task 존재.
-- **Placeholder scan:** 모든 코드 step 에 실제 코드 포함, "TBD"/"적절히 처리" 없음.
-- **Type consistency:** `resolve_task_root`/`project_rel`(Task 1) ↔ Task 3 import 일치. `_aggregate` 반환 키(`errorCount/runCount/byErrorType/bySource/byPhase/byAgent`) ↔ `render_markdown`/`build_and_write`/테스트 전부 동일. stdout JSON 키(`totals.errorCount` 등) ↔ SKILL errors.3 표 일치.
-
-**범위 밖(YAGNI):** 단일 run 모드, task-group 집계, 자동 생성 훅, HTML 뷰 — 미포함.