diff --git a/docs/ledger/README.md b/docs/ledger/README.md index 17114d5..4f664f3 100644 --- a/docs/ledger/README.md +++ b/docs/ledger/README.md @@ -7,6 +7,7 @@ 끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계, 개선 id 판정(뒤 작업 2건) ──> verdict 줄: 그 개선이 효과가 있었나, 없으면 되돌림 +평가(하네스 판 비교) ──> eval 줄: 같은 과제를 판마다 돌린 실행 하나씩 ``` - 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. @@ -23,7 +24,7 @@ | 칸 | 형식 | 뜻 | | --- | --- | --- | | `schema` | 정수 | 이 형식의 판. 지금 1 | -| `kind` | `estimate` · `actual` · `retro` · `verdict` | 줄의 종류 | +| `kind` | `estimate` · `actual` · `retro` · `verdict` · `eval` | 줄의 종류 | | `task` | 문자열 | 작업 이름. 같은 작업의 줄을 묶는 키다(예: 세션 이름) | | `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | | `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | @@ -68,3 +69,17 @@ | `ref` | 문자열 | `reverted`면 되돌린 커밋 | `task`는 판정을 내린 작업 이름이다. + +`eval`(하네스 판 비교의 실행 하나, `harness-eval` 스킬): + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `task` | 문자열 | 평가 이름(예: `harness-v2-eval`). 같은 평가의 실행을 묶는다 | +| `arm`, `case` | 문자열 | 판(예: `v1`·`v2`), 과제(예: `review-seeded-be`) | +| `active_minutes`, `calls`, `output_tokens`, `input_tokens_total` | 정수 | `actual`과 같은 규칙. 서브에이전트 기록을 더한다 | +| `start_context`, `max_context` | 정수 | 첫 호출의 입력 토큰(시작 비용), 가장 큰 호출의 입력 토큰 | +| `subagents`, `subagent_calls`, `agent_calls`, `agent_return_chars` | 정수 | 서브에이전트 기록 수와 그 호출 수, 메인이 띄운 Agent 호출 수, 서브에이전트가 메인에 돌려준 글자 수(컨텍스트 비용) | +| `findings`, `false_findings` | 정수 | 정답을 아는 과제에서 찾은 것, 틀린 발견 | +| `note` | 문자열 | 실행 방식(새 세션인가, 서브에이전트로 흉내 냈나), 모델 | + +`ledger.py compare --task <평가 이름>`이 과제·판마다 중앙값과 마지막 판/첫 판 비율을 보인다. `precedents`·회고 대기는 `eval` 줄을 세지 않는다. diff --git a/plugins/harness/scripts/ledger.py b/plugins/harness/scripts/ledger.py index 44177f8..eaf7801 100755 --- a/plugins/harness/scripts/ledger.py +++ b/plugins/harness/scripts/ledger.py @@ -11,6 +11,8 @@ current 지금 폴더의 세션 기록 경로 usage [기록 경로|uuid] 세션 기록의 실측(JSON). 하위 에이전트 기록(/subagents/)을 더한다 actual --task T [기록] T의 예측과 견준 actual 줄 초안(JSON). 쓰지는 않는다 + eval --task E --arm A --case C [기록] 평가 E의 한 실행(판 A, 과제 C) eval 줄 초안(JSON). 쓰지는 않는다 + compare --task E 평가 E의 과제·판별 중앙값 표와 마지막 판/첫 판 비율 precedents [--kind K] [--size S] 장부의 지난 예측·실측 표와 보정 줄(실측/p50 중앙값). --ledger를 여러 번 줘도 된다 pending 예측 밖인데 회고가 없는 작업, 효과 판정이 없는 개선 append stdin의 JSON 한 줄을 검사해 장부 끝에 더한다 @@ -31,16 +33,19 @@ import sys import time GAP_SECONDS = 300 -KINDS = ("estimate", "actual", "retro", "verdict") +KINDS = ("estimate", "actual", "retro", "verdict", "eval") REQUIRED = { "estimate": ("minutes", "basis"), "actual": ("active_minutes",), + "eval": ("arm", "case", "active_minutes"), "retro": ("cause", "level"), "verdict": ("fix", "effect"), } CAUSES = ("지시 모호", "착수 전 조사 부족", "아키텍처 경직", "검증 대기", "외부 대기", "범위 변경", "예측 근거 없음") LEVELS = ("architecture", "gate", "instructions", "user") EFFECTS = ("effective", "reverted") +AGENT_TOOLS = ("Agent", "Task") # 서브에이전트를 띄우는 도구 이름(옛 이름 Task) +HANDBACK_PREFIXES = ("0123456789"}}, + {"type": "attachment", "timestamp": "2026-11-07T10:03:01Z", + "attachment": {"type": "queued_command", "prompt": "사용자가 중간에 보낸 말"}}, + ], mode="a") + sub = os.path.join(self.dir, "abc", "subagents") + os.makedirs(sub) + for i in (1, 2): + with open(os.path.join(sub, "agent-%d.jsonl" % i), "w") as f: + f.write(json.dumps(self.assistant("s%d" % i, "2026-11-07T10:00:30Z", 7, cache_read=5000)) + "\n") + u = json.loads(run("ledger.py", ["usage", self.transcript], env=self.env).stdout) + self.assertEqual(u["start_context"], 1000) # 본 기록 첫 호출만, 서브에이전트 첫 호출이 아니다 + self.assertEqual((u["agent_calls"], u["agent_return_chars"]), (2, 45 + 35)) # 알림 머리 25자 + 본문 10자 + self.assertEqual((u["subagents"], u["subagent_output_tokens"]), (2, 14)) + + hook = {"session_id": "s-3", "transcript_path": self.transcript, "cwd": self.dir} + with open(self.transcript) as f: + lines = f.readlines() + with open(self.transcript, "w") as f: + f.writelines(lines[:2]) # Agent 호출까지만 쓰인 때 한 번 + run("ledger.py", ["stop"], payload=hook, env=self.env) + with open(self.transcript, "a") as f: + f.writelines(lines[2:]) + run("ledger.py", ["stop"], payload=hook, env=self.env) + with open(os.path.join(self.env["HARNESS_STATE_DIR"], "usage", "s-3.json")) as f: + saved = json.load(f)["summary"] + self.assertEqual((saved["agent_calls"], saved["agent_return_chars"]), (2, 45 + 35)) # 알림 머리 25자 + 본문 10자 + + def test_stop_hook_survives_state_saved_by_older_version(self): + self.write_transcript([self.assistant("m1", "2026-11-07T10:00:00Z", 10)]) + folder = os.path.join(self.env["HARNESS_STATE_DIR"], "usage") + os.makedirs(folder) + old = {"offset": 0, "ids": {}, "first": None, "last": None, "active": 0.0} # 0.2.0이 저장한 모양 + with open(os.path.join(folder, "s-4.json"), "w") as f: + json.dump({"session_id": "s-4", "transcript_path": self.transcript, "files": {self.transcript: old}}, f) + hook = {"session_id": "s-4", "transcript_path": self.transcript, "cwd": self.dir} + r = run("ledger.py", ["stop"], payload=hook, env=self.env) + self.assertEqual(r.stderr, "") + with open(os.path.join(folder, "s-4.json")) as f: + self.assertEqual(json.load(f)["summary"]["calls"], 1) + + def test_eval_rows_compare_arms_per_case(self): + ledger = os.path.join(self.dir, "estimates.jsonl") + bad = {"kind": "eval", "task": "e1", "case": "review"} # arm 없음 + self.assertEqual(run("ledger.py", ["append", "--ledger", ledger], payload=bad, env=self.env).returncode, 1) + rows = [] + for arm, mins, findings, start in (("v1", 20, 3, 70000), ("v1", 30, 5, 70000), + ("v2", 10, 6, 75000), ("v2", 20, 8, 75000)): + rows.append({"kind": "eval", "task": "e1", "case": "review", "arm": arm, "active_minutes": mins, + "calls": mins * 2, "output_tokens": mins * 1000, "start_context": start, + "max_context": start * 2, "findings": findings, "false_findings": 1}) + for row in rows: + self.assertEqual(run("ledger.py", ["append", "--ledger", ledger], payload=row, env=self.env).returncode, 0) + self.write_ledger(ledger, self.pair("plain", 5)) + r = run("ledger.py", ["compare", "--task", "e1", "--ledger", ledger], env=self.env) + self.assertEqual(r.returncode, 0, r.stderr) + self.assertIn("| review | v1 | 2 | 25 | 50 | 25000 | 70000 | 140000 | 4 | 1 |", r.stdout) + self.assertIn("| review | v2 | 2 | 15 | 30 | 15000 | 75000 | 150000 | 7 | 1 |", r.stdout) + self.assertIn("v2/v1 중앙값: 작업 중 분 0.60 · 호출 0.60 · 출력 0.60 · 시작 컨텍스트 1.07 · 발견 1.75", r.stdout) + self.assertNotIn("| e1 |", run("ledger.py", ["precedents", "--ledger", ledger], env=self.env).stdout) + self.assertIn("평가 줄 없음", run("ledger.py", ["compare", "--task", "none", "--ledger", ledger], + env=self.env).stdout) + + self.write_transcript([self.assistant("m1", "2026-11-07T10:00:00Z", 10)]) + r = run("ledger.py", ["eval", "--task", "e1", "--arm", "v2", "--case", "review", self.transcript], env=self.env) + draft = json.loads(r.stdout) + self.assertEqual((draft["kind"], draft["arm"], draft["case"], draft["calls"]), ("eval", "v2", "review", 1)) + self.assertIn("findings", draft) + self.assertIn("false_findings", draft) + def test_nudge_prints_one_line_once_per_repo_on_startup(self): repo = os.path.join(self.dir, "repo") os.makedirs(repo) diff --git a/template/docs/ledger/README.md b/template/docs/ledger/README.md index 17114d5..4f664f3 100644 --- a/template/docs/ledger/README.md +++ b/template/docs/ledger/README.md @@ -7,6 +7,7 @@ 끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측 회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계, 개선 id 판정(뒤 작업 2건) ──> verdict 줄: 그 개선이 효과가 있었나, 없으면 되돌림 +평가(하네스 판 비교) ──> eval 줄: 같은 과제를 판마다 돌린 실행 하나씩 ``` - 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다. @@ -23,7 +24,7 @@ | 칸 | 형식 | 뜻 | | --- | --- | --- | | `schema` | 정수 | 이 형식의 판. 지금 1 | -| `kind` | `estimate` · `actual` · `retro` · `verdict` | 줄의 종류 | +| `kind` | `estimate` · `actual` · `retro` · `verdict` · `eval` | 줄의 종류 | | `task` | 문자열 | 작업 이름. 같은 작업의 줄을 묶는 키다(예: 세션 이름) | | `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | | `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects/<폴더>/<이 값>.jsonl`). 실측을 다시 셀 때 쓴다 | @@ -68,3 +69,17 @@ | `ref` | 문자열 | `reverted`면 되돌린 커밋 | `task`는 판정을 내린 작업 이름이다. + +`eval`(하네스 판 비교의 실행 하나, `harness-eval` 스킬): + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `task` | 문자열 | 평가 이름(예: `harness-v2-eval`). 같은 평가의 실행을 묶는다 | +| `arm`, `case` | 문자열 | 판(예: `v1`·`v2`), 과제(예: `review-seeded-be`) | +| `active_minutes`, `calls`, `output_tokens`, `input_tokens_total` | 정수 | `actual`과 같은 규칙. 서브에이전트 기록을 더한다 | +| `start_context`, `max_context` | 정수 | 첫 호출의 입력 토큰(시작 비용), 가장 큰 호출의 입력 토큰 | +| `subagents`, `subagent_calls`, `agent_calls`, `agent_return_chars` | 정수 | 서브에이전트 기록 수와 그 호출 수, 메인이 띄운 Agent 호출 수, 서브에이전트가 메인에 돌려준 글자 수(컨텍스트 비용) | +| `findings`, `false_findings` | 정수 | 정답을 아는 과제에서 찾은 것, 틀린 발견 | +| `note` | 문자열 | 실행 방식(새 세션인가, 서브에이전트로 흉내 냈나), 모델 | + +`ledger.py compare --task <평가 이름>`이 과제·판마다 중앙값과 마지막 판/첫 판 비율을 보인다. `precedents`·회고 대기는 `eval` 줄을 세지 않는다.