# 간소 재배치 보고서 갱신

<!-- DOC:AUTHOR -->
갱신 2026-10-18 · 저자: 홍지혜(jhhong)
<!-- /DOC:AUTHOR -->

갱신 2026-10-18 · 저자: 홍지혜(jhhong)

운영 규칙은 [../AGENTS.md](../AGENTS.md)가 정본입니다. HTML의 전후 비교 UI를 유지하면서
판정 이력·회차별 입력 대비 BAD·추세·코드·규칙 측정을 함께 생성합니다.
기본 추세는 원본 3,114장에 각 버전의 변경분 판정을 교체한 전체 BAD율입니다.
`population.pages`에는 모든 원본 페이지의 판정 출처(원판정/해당 회차/미판정)를 저장합니다.

## 실행

```sh
./tracking/refresh.sh --check          # 연결 검증·변경 여부만 확인
./tracking/refresh.sh                  # 변경 있으면 보관 → 갱신 → 검사 → 불변 ZIP
./tracking/refresh.sh --force          # 빠른 변경 감지를 건너뛰고 내용 해시 재검사
```

실행 위치는 보고서 폴더입니다. Python은 사전 설치된
`~/.local/share/miridih-dictionary/relayout-venv/bin/python`(사전 폴더 밖 — 배포 시크릿 검사가 venv 안 라이브러리를 오탐해 2026-10-25 옮김)을 사용합니다. 의존성은 `requirements.txt`에 고정합니다.
`node`는 생성 JS 문법 검증, `gh`는 PR 읽기 전용 상태 확인에 사용합니다.

## 새 판정 추가

1. 완료된 `round-…-material/` 안에 원본 `DATA.md`, `PROMPTS.md`, `cells.csv`를 함께 둡니다.
2. 해당 업로드를 만든 `judge-simpleA/B-….csv`와 `.index.json`도 보고서 폴더에 둡니다.
3. 표준 이름이면 업로드의 공개 `source.csv` 바이트와 로컬 CSV를 대조해 자동 연결합니다.
   연결이 불명확하면 같은 material 폴더에 `round.json`을 추가합니다.

```json
{
  "arm": "A",
  "complete": true,
  "export_csv": "judge-simpleA-실제파일명.csv",
  "index": "judge-simpleA-실제파일명.index.json",
  "at": "2026-10-18T04:00:00Z",
  "model": "실제 모델명",
  "prompt_bundle": 8,
  "input_commit": "실제 입력 커밋 SHA",
  "relayout_commit": "실제 알고리즘 커밋 SHA",
  "export_commit": "실제 내보내기 HEAD"
}
```

위 값은 형식 예시입니다. 파일의 수정 시각이나 내보내기 HEAD로 판정 시각·알고리즘 코드를 추측하지 않습니다.
확인하지 못한 값은 생략하면 미기록으로 표시합니다. `complete: true`는 실제 완료를 확인한 뒤만 적습니다.
기존 `run_id/variant/ref/rep` 판정 수정·삭제는 거부하며, 새 회차나 반복으로 추가해야 합니다.
3,114장 원본 모수가 달라진 실험은 별도 보고서/명시적 모수 마이그레이션이 필요합니다.

## 규칙 지표 연결

- 기존 d2561c903 실행은 `rule-profiles.json`의 CSV 해시와 `evidence/evaluation-code-versions.json`의
  알고리즘·안전 조건 소스 해시로 연결합니다.
- 새 실행은 `judge-simple-*.manifest.json`의 출력 CSV 해시, 평가 metadata/eval.jsonl 해시,
  algorithmCommit, 페이지별 결과 JSON 해시를 확인해 연결합니다.
- 현재 새 manifest 어댑터는 `raw-glyph-actual-outline` 실행 형식입니다. 다른 평가 형식은
  `rules.py`에 검증 가능한 어댑터를 추가합니다. 이름만 비슷한 지표를 섞지 않습니다.
- 새 판정에 대응하는 실행 근거가 없으면 ‘연결된 규칙 측정 없음’과 이전 측정 기록을 표시합니다.
  같은 결과의 재판정은 원래 측정 시각·수치를 유지합니다.

## 파일과 실패 처리

| 파일 | 역할 |
|---|---|
| `rounds.json` | 초기 회차와 코드·CSV·index 등록 |
| `source-pages.json` | 원본 3,114장의 키·D.O.·입력·summary·route 기준 |
| `data.py` | 동일 원본 검증, 반복 중앙값, 판정 누적·환산 |
| `rules.py` / `rule-profiles.json` | 실행 근거를 출력과 연결하고 규칙 지표 집계 |
| `render.py` | 기존 카드·이미지를 유지하는 HTML 갱신 |
| `render_pipeline_flow.py` / `pipeline.json` | 입력부터 화면 표시까지의 호출 흐름·계산기와 고정 커밋 소스 대조 |
| `update.py` / `release.py` / `verify.py` | 보관·버전·검사·원자적 교체·불변 ZIP |
| `snapshot.json` | 모든 판정 회차·페이지 대응·사례별 누적 이력 |
| `ledger.json` | 과거 판정 셀별 SHA-256, 덮어쓰기·누락 방지 |
| `state.json` | 마지막 성공 버전·원본 지문 |
| `status.json` | 마지막 실질 갱신 성공 또는 오류 이유 |
| `cache/` | 이미지·업로드 CSV 읽기 전용 캐시 |

검증 실패 시 마지막 정상 HTML을 유지합니다. 잘못된 새 자료를 고쳐 다시 실행합니다.
`ledger.json`을 지워서 과거 판정 변조 검사를 우회하지 않습니다. 반복 실행에 내용 변경이 없으면
버전·본문 갱신일·아카이브를 추가하지 않습니다. 새 회차·반복 추가는 MINOR,
기존 판정 기준을 유지한 자동화·표시 정정은 PATCH로 기록합니다. ZIP으로 릴리스된 버전은 수정하지 않습니다.

## 로컬 자동 감시

설정 정본: `../../launchd/com.miridih.dictionary.relayout-report.plist`.
사용자 로그인 세션의 launchd에서 60초 간격으로 확인하며, 보고서 폴더 변경도 감지합니다.
`--quiet`는 변화 없는 확인을 로그에 쓰지 않습니다. 설치/실행 상태 확인:

```sh
launchctl print gui/$(id -u)/com.miridih.dictionary.relayout-report
cat tracking/status.json
```

로컬에 **완료 material이 추가된 뒤** 자동 반영됩니다. 로그인 필요한 평가 서버의 새 판정을
자동 다운로드하거나 LLM·재배치를 실행하거나 사이트를 배포하지 않습니다. 컴퓨터가 꺼져 있거나
로그아웃된 동안에는 실행하지 않고 다음 로그인에서 다시 확인합니다. 열린 HTML은 새로고침해야 합니다.

해제: `launchctl bootout gui/$(id -u)/com.miridih.dictionary.relayout-report`.

## 검증

```sh
~/.local/share/miridih-dictionary/relayout-venv/bin/python -m unittest discover -s tracking -p 'test_*.py'
python3 ../../validate-docs.py
```

DOM 상호작용 검사는 `check-dom.cjs`를 사용합니다. 실제 브라우저 렌더 검증과 구분합니다.

## 변화 진단과 검토 메모

`diagnostics.py`는 전체 BAD 증감을 서로 겹치지 않는 페이지 구간으로 분해하고,
동일 이미지의 재판정 변동과 실제 이미지 변경을 따로 계산합니다. 결과는
`snapshot.json`의 `diagnostics`에 포함됩니다. `render_diagnostics.py`는 이 근거를
결과·추세·개별 사례·실행 방식 탭에 반영합니다.

`reviews.json`에는 직접 검토한 회차/커밋, 원본 페이지, 관측·원인 후보·개선안과
근거 파일을 등록합니다. 새 판정에서 과거 검토를 현재 결론으로 자동 재사용하지 않습니다.
새 회차 자동 갱신은 계속 MINOR이며, 수동 분석 설명을 추가할 때도 다음처럼 MINOR를 지정할 수 있습니다.

```sh
./tracking/refresh.sh --force --change-type MINOR --reason '직전 대비 BAD 변화 분해와 사례 분석 추가'
```

## 판정 전 로컬 구현 검증 · 실행 방식 탭

`implementation.json`은 기존 판정 이후의 미커밋 구현 검증을 `#pipeline`에 따로 표시합니다.
기준 커밋·소스 SHA-256·적용 patch·3,114장 고정 입력 재실행·22페이지 후보 로그·대표 렌더를 함께 등록합니다.
근거 파일은 `artifacts`의 SHA-256과 대조합니다. 이 파일은 판정 회차/원본 모수/규칙 실측 데이터로 가져오지 않습니다.
새 LLM 결과가 들어와도 과거 구현 검증의 날짜와 기준을 유지하며 현재 BAD로 덮어쓰지 않습니다.
검증 근거를 교체할 때는 같은 해시 검증·MINOR 보관 절차를 적용합니다.

`implementation-followup.json`은 판정 전 구현이 실제 커밋·완료 판정으로 이어진 연결과, 같은 채점 규칙으로 대조한 직전/현재 결과를 보존합니다. 과거 `implementation.json`의 예측 근거는 덮어쓰지 않습니다. `pipeline.json`의 호출 경로는 새 커밋의 소스 바이트와 다시 대조한 뒤 갱신합니다.