refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,396 @@
+# keycloak-session-store 최종 검수 리뷰
+
+- 검토일: 2026-09-20
+- 대상: `reviews/2026-09-20-keycloak-session-store-post-remediation-verification.md` 반영 결과
+- 판정: **아직 더 봐야댐**
+
+## 1. 결론
+
+이전 후속 리뷰에서 완료 차단으로 잡았던 핵심 항목은 **대부분 제대로 반영됐다.**
+
+이번 검수에서 확인한 완료 항목:
+
+1. `--repo` evidence gate 우회 제거
+2. source repository 부재를 `UNVERIFIABLE`로 명시적으로 모델링
+3. run verifier가 잘못된 evidence gate를 실제 FAIL시키도록 보강
+4. 33개 command-bearing Record / 992 shell block의 현재 project-level audit 작성
+5. Tree / 문체 / command parser 개선 유지
+6. 전체 project gate PASS
+7. 전체 pipeline exit 0
+8. 전체 unittest **406 PASS / 14 skipped**
+
+따라서 **검증 계약과 command audit 문제는 이번에는 제대로 닫혔다.**
+
+남은 것은 한 축뿐이다.
+
+> **TechViz 7개의 주변 context snapshot warning이 아직 남아 있다.**
+
+그림이 직접 근거로 삼는 `current_section`은 31/31 최신 SSOT와 일치하므로 그림의 기술 내용이 틀렸다고 보지는 않는다. 하지만 이전 리뷰에서 최종 cleanup 대상으로 지정한 warning이 실제 verifier에 그대로 남아 있으므로 아직 `완료`로 넘기지는 않는다.
+
+---
+
+## 2. evidence gate — 반영 완료
+
+새 schemaVersion 5 verification run 6개를 확인했다.
+
+각 run의 S3/S5/S6 evidence gate는 실제로:
+
+```bash
+node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs keycloak-session-store --repo
+```
+
+를 실행하고 있다.
+
+현재 머신에는 source repository가 없으므로 결과는:
+
+```text
+exit: 3
+status: UNVERIFIABLE
+semanticId: evidence-repo
+reason: source repository unavailable on current machine
+acceptedByProjectReview: true
+```
+
+로 보존된다.
+
+대상 6 run 모두:
+
+```text
+verify-pipeline-run.py
+→ PASS
+→ live source UNVERIFIABLE=['S3', 'S5', 'S6']
+```
+
+이다.
+
+즉 이전처럼 `--repo`를 빼고 exit 0을 만든 것이 아니다.
+
+### technicalEvidence도 일치
+
+각 run의 `qualityReviews.technicalEvidence`에도:
+
+```text
+liveSourceReconciliation: UNVERIFIABLE
+liveSourceReason: source repository unavailable on current machine
+acceptedByProjectReview: true
+```
+
+가 기록되어 stage gate 상태와 일치한다.
+
+이 항목은 **완료**다.
+
+---
+
+## 3. run verifier blind spot — 반영 완료
+
+verifier가 필드만 읽고 형식적으로 PASS하는지 확인하기 위해 실제 v5 run을 /tmp 사본으로 변조해 음성 테스트를 했다.
+
+### case 1 — `--repo` 삭제
+
+변조:
+
+```text
+check_evidence ... keycloak-session-store
+exit 0
+status PASS
+```
+
+결과:
+
+```text
+PIPELINE RUN: FAIL
+live source evidence gate에서 --repo가 빠졌다
+```
+
+### case 2 — UNVERIFIABLE reason 삭제
+
+결과:
+
+```text
+PIPELINE RUN: FAIL
+UNVERIFIABLE evidence gate에 이유가 없다
+```
+
+### case 3 — semanticId 삭제
+
+결과:
+
+```text
+PIPELINE RUN: FAIL
+필수 evidence semantic gate가 정확히 하나가 아니다
+```
+
+따라서 이전 verifier blind spot은 닫혔다.
+
+이 항목은 **완료**다.
+
+---
+
+## 4. 33 Record / 992 command audit — 반영 완료
+
+프로젝트 내부에 다음 current audit이 추가됐다.
+
+```text
+docs/keycloak-session-store/reviews/
+  2026-09-20-keycloak-session-store-command-audit.json
+  2026-09-20-keycloak-session-store-command-audit.md
+```
+
+현재 JSON audit과 실제 파일을 다시 대조했다.
+
+```text
+records     33
+shellBlocks 992
+findings     53
+major         0
+text-like    15
+SHA mismatch  0
+detail mismatch 0
+```
+
+33개 Record 전부 현재 파일 SHA256과 맞는다.
+
+finding 상세도 현재 analyzer를 다시 실행한 결과와 정확히 일치한다.
+
+남은 finding:
+
+```text
+hidden-stderr          48
+compound-remote-shell   5
+```
+
+은 모두 minor이고 audit에서 문맥 검토 후 허용 상태로 남겼다.
+
+projectVerdict도:
+
+```text
+PASS
+```
+
+다.
+
+옛 run을 소급 수정하지 않고 현재 audit을 별도 artifact로 남긴 방식도 이전 리뷰의 요구와 맞는다.
+
+이 항목은 **완료**다.
+
+---
+
+## 5. 문체 / Tree / Record — 정상
+
+현재:
+
+```text
+records=61
+written=61
+unwritten=0
+
+prose 61/61 PASS
+voice 61/61 PASS
+```
+
+Tree의 이전 미처분 절도:
+
+```text
+KEEP_IN_SSOT
+CONFIRMED
+```
+
+상태를 유지한다.
+
+Required Content, SSOT Facts, Audit도 모두 PASS다.
+
+추가 문체 수정 finding은 이번 검수에서 발견하지 못했다.
+
+---
+
+## 6. Figure gate — 내용은 정상
+
+현재:
+
+```text
+Figure Text       PASS 31/31
+Figure Overlap    PASS 31/31
+Figure Provenance PASS 31/31
+```
+
+그리고 각 TechViz가 직접 근거로 삼는:
+
+```text
+current_section exact match = 31 / 31
+```
+
+이다.
+
+따라서 **그림의 직접 기술 근거는 현재 SSOT와 맞는다.**
+
+---
+
+## 7. 유일한 잔여 finding — stale surrounding context 7개
+
+`verify-project-layout.py keycloak-session-store`에는 아직 다음 경고가 남는다.
+
+```text
+SSOT 문맥이 바뀐 뒤 그림을 다시 보지 않았다: 7
+```
+
+정확한 대상과 mismatch:
+
+### 1. a1-transport-vs-discovery
+
+```text
+previous_section STALE — A층 — Keycloak 자체가 깨질 때
+current_section  MATCH — A-1 · JGroups 전송(TCP 7800) 차단
+next_section     MATCH — A-2 · A-3 — DB 가 멈출 때와 죽을 때
+```
+
+### 2. d2-upgrade-direction
+
+```text
+previous_section STALE — D층 — 운영
+current_section  MATCH — D-1 · D-2 — 백업과 업그레이드
+next_section     MATCH — D-3 · 비밀
+```
+
+### 3. lab-topology
+
+```text
+previous_section STALE — 문제를 어렵게 만든 제약
+current_section  MATCH — 실험대
+next_section     MATCH — 게스트와 호스트의 sudo 가 다르다
+```
+
+### 4. measurement-control
+
+```text
+previous_section STALE — 결정이 지켜지는지 확인하는 방법
+current_section  MATCH — 측정이 거짓말할 때
+next_section     MATCH — 재현 가능성을 어떻게 보장했나
+```
+
+### 5. observation-points
+
+```text
+previous_section STALE — 검토한 선택지와 막힌 지점
+current_section  MATCH — 관측을 어디에 둘 것인가
+next_section     MATCH — 스크립트를 쓰지 않는다
+```
+
+### 6. open-questions-answered
+
+```text
+previous_section STALE — 얻은 것, 잃은 것, 적용하지 않을 때
+current_section  MATCH — 열린 질문 네 개에 대한 답
+next_section     MATCH — 이 기록이 적용되지 않는 조건
+```
+
+### 7. wrong-predictions
+
+```text
+previous_section MATCH — 얻은 것, 잃은 것, 적용하지 않을 때
+current_section  MATCH — 결국 지키려던 것은 무엇이었나
+next_section     STALE — 자료
+```
+
+### 판단
+
+이 7개는 **그림의 직접 source section mismatch가 아니다.**
+
+여섯 개는 parent/previous section이 이후 child section 변경까지 포함하면서 stale이 되었고, 하나는 뒤의 `자료` section이 변경된 경우다.
+
+즉 semantic node/edge를 다시 설계해야 한다는 evidence는 현재 없다.
+
+하지만 현재 canonical verifier가 stale context로 잡고 있고 이전 리뷰에서 이 warning을 마지막에 닫으라고 명시했으므로 **최종 cleanup이 아직 남아 있다.**
+
+---
+
+## 8. 필요한 마지막 작업
+
+SVG를 손으로 수정하지 않는다.
+
+7개에 대해서만 canonical TechViz 흐름으로:
+
+1. 현재 `final/document.md`에서 context 재생성
+2. 기존 spec의 semantic node/edge가 여전히 맞는지 확인
+3. 의미 변경이 없으면 context/evidence hash만 최신화
+4. 필요한 canonical render 실행
+5. Figure Text / Overlap / Provenance
+6. preview 눈 확인
+7. `verify-project-layout.py keycloak-session-store`
+
+를 다시 실행한다.
+
+목표:
+
+```text
+SSOT 문맥이 바뀐 뒤 그림을 다시 보지 않았다 = 0
+```
+
+이다.
+
+parent/neighbor section 전체를 snapshot으로 잡는 현재 context 모델 때문에 재생성 후에도 같은 경고가 반복된다면, 그때는 억지로 context를 고치지 말고 `verify-project-layout.py`의 context 비교 모델을 수정하고 regression test를 추가한다.
+
+---
+
+## 9. 현재 전체 검증
+
+프로젝트:
+
+```text
+verify-tech-log-tree       PASS
+verify-project-layout      PASS (stale-context warn 7 포함)
+audit-records              PASS
+check-figure-text          PASS 31/31
+check-figure-overlap       PASS 31/31
+check-figure-provenance    PASS 31/31
+check-required-content     PASS 61
+check-ssot-facts           PASS
+git diff --check           PASS
+
+prose                     PASS 61/61
+voice                     PASS 61/61
+```
+
+v5 evidence runs:
+
+```text
+6 / 6 PASS
+UNVERIFIABLE 상태 정상 보존
+```
+
+전체 pipeline:
+
+```text
+verify-pipeline.py
+exit 0
+```
+
+전체 tests:
+
+```text
+Ran 406 tests
+OK
+skipped=14
+```
+
+---
+
+## 10. 최종 판정
+
+이전 리뷰의 핵심 문제였던:
+
+- evidence `--repo` 우회
+- UNVERIFIABLE 모델 부재
+- run verifier blind spot
+- 33 Record command audit 부재
+
+는 이번에는 **제대로 수정됐다.**
+
+문서 내용, command audit, 검증 계약도 현재 정상이다.
+
+그러나 이전 리뷰에서 마지막 cleanup으로 요구한 **TechViz stale surrounding-context warning 7개가 아직 남아 있다.**
+
+따라서 현재 판정은:
+
+> **keycloak-session-store = 아직 더 봐야댐**
+
+7개 context warning만 닫고 다시 project gate → 전체 pipeline → unittest를 순차 실행하면 된다.