Files
clean-architecture-backend-…/scripts/tests/test_ledger.py
T
DongHyeonka 37c88fedd4 docs(ledger): 작업마다 예측과 실측을 쌓는 repo 장부를 둔다
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).

- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
  뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
  실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
  merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
  더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
  근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.

버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.

위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.

검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
2026-11-07 22:11:27 +09:00

54 lines
2.2 KiB
Python

"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다.
python3 -m unittest discover -s scripts/tests
"""
from __future__ import annotations
import json
import unittest
from datetime import datetime
from pathlib import Path
REPO = Path(__file__).resolve().parent.parent.parent
LEDGER = REPO / "docs/ledger/estimates.jsonl"
KINDS = {"estimate", "actual", "retro"}
COMMON = ("schema", "kind", "task", "recorded_at")
RANGES = ("minutes", "calls", "output_tokens")
def lines() -> list[dict]:
return [json.loads(line) for line in LEDGER.read_text(encoding="utf-8").splitlines() if line.strip()]
class LedgerTest(unittest.TestCase):
def test_every_line_is_json_with_the_common_fields(self) -> None:
for number, entry in enumerate(lines(), start=1):
self.assertTrue(set(COMMON) <= entry.keys(), f"line {number}: {sorted(set(COMMON) - entry.keys())}")
self.assertEqual(entry["schema"], 1, number)
self.assertIn(entry["kind"], KINDS, number)
datetime.fromisoformat(entry["recorded_at"])
def test_an_estimate_has_ordered_ranges_and_a_basis(self) -> None:
for entry in (e for e in lines() if e["kind"] == "estimate"):
for field in RANGES:
values = entry[field]
self.assertLessEqual(values["p30"], values["p50"], (entry["task"], field))
self.assertLessEqual(values["p50"], values["p80"], (entry["task"], field))
self.assertTrue(entry["basis"].strip(), entry["task"])
def test_an_actual_follows_its_estimate_and_names_the_band_it_fell_in(self) -> None:
entries = lines()
for position, entry in enumerate(entries):
if entry["kind"] != "actual":
continue
estimates = [e for e in entries[:position] if e["kind"] == "estimate" and e["task"] == entry["task"]]
self.assertTrue(estimates, f"{entry['task']}: an actual line needs an earlier estimate line")
bands = estimates[-1]["minutes"]
expected = next((band for band in ("p30", "p50", "p80") if entry["active_minutes"] <= bands[band]), "over")
self.assertEqual(entry["within"], expected, entry["task"])
if __name__ == "__main__":
unittest.main()