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,428 @@
+# Keycloak 최종 검증 리뷰 — current remediation 재검토
+
+- 검토일: 2026-09-20
+- 대상: `docs/keycloak`, `runs/keycloak`
+- 기준: 현재 7단계 TechLog 하네스 계약
+- 최종 판정: **아직 더 봐야댐**
+
+---
+
+## 1. 결론
+
+문서 내용 자체는 이전 리뷰의 지적사항이 정상적으로 반영됐다.
+
+다음 항목은 모두 다시 확인했고 문제를 찾지 못했다.
+
+- 기록 24개 Tree / Layout 기본 구조
+- Required Content
+- SSOT fact 형식 검사
+- Natural Prose
+- Voice
+- Command Pedagogy
+- Figure Text
+- Figure Overlap
+- Figure Provenance
+- 전체 pipeline
+- 전체 unittest
+
+새로 만든 17개의 current remediation run도 `verify-pipeline-run.py` 자체는 **17/17 PASS**한다.
+
+하지만 현재 하네스의 실제 계약과 원장 내용을 다시 대조하면 **아직 완료로 볼 수 없는 절차 문제가 남아 있다.**
+
+핵심은 두 가지다.
+
+1. current remediation에서 별도 subagent를 사용하지 않았다는 사실이 원장에 직접 남아 있다.
+2. S3/S5/S6의 evidence gate가 계약상 필요한 `--repo` 없이 실행됐다.
+
+추가로 SVG 2개의 SSOT context/manifest도 stale 상태다.
+
+따라서 Keycloak은 아직 다음 프로젝트로 넘기지 않는다.
+
+> **keycloak = 아직 더 봐야댐**
+
+---
+
+# 2. 재검증 결과
+
+## 2.1 Current remediation run
+
+2026-09-19 current remediation run:
+
+```text
+17 runs
+17/17 verify-pipeline-run.py PASS
+schemaVersion = 4
+```
+
+수정된 17개 Record와 17개 current run의 record mapping도 일치한다.
+
+## 2.2 Keycloak 프로젝트 검사
+
+```text
+verify-tech-log-tree.py keycloak
+PASS
+records=24
+topics=1
+nodes=24
+written=24
+unwritten=0
+
+verify-project-layout.py keycloak
+PASS
+error=0
+
+audit-records.py keycloak
+PASS
+
+check-figure-text.py keycloak
+PASS
+
+check-figure-overlap.py keycloak
+PASS
+
+check-figure-provenance.py keycloak
+PASS
+
+check-required-content.py keycloak
+PASS
+
+check-ssot-facts.py keycloak
+PASS
+
+git diff --check -- docs/keycloak runs/keycloak reviews
+PASS
+```
+
+## 2.3 S5 / S6 / Command Pedagogy
+
+24개 Record 전체를 다시 검사했다.
+
+```text
+Natural Prose: PASS 24/24
+Voice:         PASS 24/24
+Command:       PASS 24/24
+```
+
+Keycloak 기록에는 shell/CLI block이 없으므로 command lane은 정상적으로 N/A다.
+
+## 2.4 전체 회귀
+
+```text
+verify-pipeline.py
+exit 0
+```
+
+전체 테스트:
+
+```text
+Ran 391 tests
+OK (skipped=14)
+```
+
+---
+
+# 3. F-01 — current remediation이 실제 subagent 분리 계약을 충족하지 않음
+
+**등급: 완료 차단**
+
+현재 하네스는 단순히 역할 이름을 원장에 적는 것이 아니라 각 단계마다 정해진 subagent를 별도로 실행하는 구조다.
+
+`running-tech-log-pipeline/SKILL.md`와 `stage-contracts.md`는 다음을 요구한다.
+
+```text
+S3 -> record-writer
+S4 -> diagram-maker
+S5 -> prose-rewriter
+S6 -> voice-writer
+technical evidence review -> fact-reviewer
+```
+
+그리고 이 역할을 일반 세션이 대신 수행하는 것이 아니라 `Agent(subagent_type="...")` 형태로 분리하는 것이 이 하네스의 목적이다.
+
+그런데 새 current remediation 원장의 `technicalEvidence.notes`에는 17개 모두 다음 사실이 직접 기록돼 있다.
+
+```text
+별도 Agent tool은 노출되지 않아 current remediation 세션이
+fact-reviewer 계약을 직접 수행했다.
+```
+
+즉 원장의:
+
+```json
+"runBy": "fact-reviewer"
+```
+
+와 실제 실행 설명이 일치하지 않는다.
+
+`verify-pipeline-run.py`는 `runBy` 문자열이 계약상의 에이전트 이름인지와 해당 agent 정의 파일이 존재하는지를 검사한다.
+
+하지만 저장소 밖에서 실제로 `Agent(subagent_type="fact-reviewer")`가 실행됐는지까지 증명하지는 않는다.
+
+따라서 **기계 검사는 PASS지만 현재 원장 자체의 notes가 subagent isolation을 수행하지 않았다고 밝히고 있다.**
+
+### 수정 원칙
+
+기존 2026-09-19 remediation run을 고쳐서 마치 subagent가 실행된 것처럼 만들면 안 된다.
+
+현재 run은 현재 시점의 실행 영수증으로 그대로 둔다.
+
+별도 Agent/subagent 실행이 가능한 환경에서 **새 current remediation run을 다시 수행**해야 한다.
+
+최소한 S3, S5, S6, fact-review는 계약에 지정된 독립 agent가 실제로 수행해야 한다.
+
+---
+
+# 4. F-02 — S3/S5/S6 evidence gate에 `--repo`가 빠짐
+
+**등급: 완료 차단**
+
+현재 stage contract의 S3 gate는 명확히 다음 명령을 요구한다.
+
+```bash
+node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo
+```
+
+S5와 S6도 문장 수정 이후 **S3 gate를 다시 실행**하는 계약이다.
+
+하지만 17개 current remediation run을 전부 확인하면 S3/S5/S6가 다음 형태로 기록되어 있다.
+
+```bash
+node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs keycloak
+```
+
+즉 `--repo`가 빠져 있다.
+
+결과:
+
+```text
+missing --repo:
+17/17 runs
+S3, S5, S6 모두
+```
+
+이 차이는 단순 옵션 차이가 아니다.
+
+현재 올바른 계약 명령을 직접 실행하면:
+
+```text
+node .../check_evidence.mjs keycloak --repo
+
+[keycloak] 증빙 대조 (저장소 포함)
+? 1 저장소 경로가 이 기계에 없다
+  /home/donghyeon/workspace/keycloak-pattern
+
+불일치 0건 · 대조 불가 1건
+
+exit=3
+```
+
+즉 현재 원장의 evidence gate `exit=0`은 **source repository까지 대조해서 PASS한 결과가 아니다.**
+
+하네스 SKILL도 exit code를 다음처럼 구분한다.
+
+- 0: repo 대조 완료
+- 1: 실제 불일치
+- 2: 검사 대상 성립 안 함
+- 3: source repository 부재 → UNVERIFIABLE
+
+현재 source repo가 없는 상태에서 `--repo`를 빼고 exit 0을 기록하면 이 구분이 사라진다.
+
+### 수정 원칙
+
+가장 올바른 해결은 source repository를 현재 머신에서 실제로 접근 가능하게 만드는 것이다.
+
+현재 정본 경로:
+
+```text
+/home/donghyeon/workspace/keycloak-pattern
+```
+
+은 존재하지 않는다.
+
+`/shared/document-haness/.run/keycloak-four-patterns`도 확인했지만 이는 Record 작업 산출물이고 source repository 대체물이 아니다.
+
+source repository를 준비한 뒤 새 remediation run에서 S3/S5/S6의 `check_evidence.mjs keycloak --repo`를 실제로 통과시켜야 한다.
+
+기존 2026-09-19 run의 gate 명령이나 exit code를 사후 수정하지 않는다.
+
+---
+
+# 5. F-03 — SVG 2개의 source context manifest가 stale
+
+**등급: 수정 필요**
+
+현재 project layout은 error 0으로 PASS하지만 다음 경고가 남아 있다.
+
+```text
+SSOT 문맥이 바뀐 뒤 그림을 다시 보지 않았다
+
+- ap1-direct-architecture
+- login-api-phase-split
+```
+
+현재 두 TechViz `context.json` / `spec.json`은 새 SSOT hash를 가리킨다.
+
+```text
+current document/context sha256
+ea10df24b892e2c57123a37a4b4f0d821e4f394353e6746f50df6a48342353e9
+```
+
+하지만 두 asset manifest는 이전 source context hash를 계속 갖고 있다.
+
+```text
+manifest source_context.document_sha256
+15e7c79412ac05ed39d6f3d0c14de8dda92abe7b402139ac2a90492dfe5e162c
+```
+
+### 의미
+
+Spec의 evidence line/hash는 새 SSOT에 맞게 갱신됐지만 최종 render/review 영수증인 manifest가 새 context 기준으로 닫히지 않았다.
+
+현재 diff를 보면 도식의 node/edge 구조를 바꿔야 할 정도의 의미 변경은 확인되지 않았다.
+
+- AP1: public client 설명의 scope가 더 정확하게 바뀜
+- login/API split: 도식 핵심 흐름 자체는 유지됨
+
+따라서 새 그림을 설계할 필요는 없다.
+
+### 필요한 조치
+
+TechViz 정본을 기준으로 두 그림만 다시 render/review한다.
+
+대상:
+
+```text
+ap1-direct-architecture
+login-api-phase-split
+```
+
+그 뒤:
+
+```text
+techviz lint
+check-figure-text.py
+check-figure-overlap.py
+preview-figure.py
+check-figure-provenance.py
+verify-project-layout.py keycloak
+```
+
+를 다시 돌린다.
+
+목표는 `SSOT 문맥이 바뀐 뒤 그림을 다시 보지 않았다` 경고 2건을 없애는 것이다.
+
+SVG를 손으로 편집하지 않는다.
+
+---
+
+# 6. 완료 차단이 아닌 항목
+
+## 6.1 Historical record run coverage
+
+전체 pipeline은 현재 Keycloak 24개 중 22개가 어떤 run ledger에 덮여 있다고 보고한다.
+
+원장이 없는 historical record:
+
+```text
+concept-forward-auth-and-auth-request.md
+decision-federation-not-a-pattern.md
+```
+
+이 두 기록을 위해 과거 run ledger를 소급 생성하지 않는다.
+
+현재 하네스 원칙상 historical ledger 부재 자체를 이번 remediation의 실패로 바꾸지 않는다.
+
+## 6.2 Source repository absence
+
+현재 source repository가 없으므로 live source reconciliation은:
+
+```text
+UNVERIFIABLE
+```
+
+이다.
+
+이를 PASS라고 쓰면 안 된다.
+
+다만 문서 본문 자체의 기존 수정 사항은 SSOT / local evidence 기준으로 재검토했고 새로운 내용 오류는 찾지 못했다.
+
+---
+
+# 7. 현재 완료 조건
+
+## 내용 / 문체 / SVG 구조
+
+- [x] 기존 리뷰의 문서 내용 finding 반영
+- [x] Bearer JWT validation chain SVG
+- [x] IdP Brokering SVG
+- [x] Natural Prose 24/24 PASS
+- [x] Voice 24/24 PASS
+- [x] Command 24/24 PASS
+- [x] Figure Text PASS
+- [x] Figure Overlap PASS
+- [x] Figure Provenance PASS
+- [x] Required Content PASS
+- [x] Tree PASS
+- [x] 전체 pipeline exit 0
+- [x] unittest 391 PASS / 14 skipped
+
+## 남은 완료 차단
+
+- [ ] source repository를 실제 대조 가능한 위치에 준비
+- [ ] 새 current remediation run에서 S3 evidence gate를 `--repo`로 실행
+- [ ] S5 evidence gate를 `--repo`로 재실행
+- [ ] S6 evidence gate를 `--repo`로 재실행
+- [ ] S3/S5/S6를 실제 지정 subagent로 수행
+- [ ] fact-reviewer를 실제 독립 subagent로 수행
+- [ ] 새 run ledger 각각 `verify-pipeline-run.py` PASS
+- [ ] `ap1-direct-architecture` manifest/context 재검토
+- [ ] `login-api-phase-split` manifest/context 재검토
+- [ ] `verify-project-layout.py keycloak`에서 위 stale-context 경고 2건 제거
+- [ ] 마지막 전체 pipeline / unittest 재실행
+
+---
+
+# 8. 다음 작업 지시
+
+현재 Keycloak 본문을 다시 대규모 수정하지 않는다.
+
+다음 실행의 범위는 **절차 증빙과 stale SVG 2개만**이다.
+
+순서:
+
+```text
+1. keycloak-pattern source repo를 현재 머신에 준비
+2. current remediation run 새로 시작
+3. 지정 subagent로 S3 수행
+4. check_evidence.mjs keycloak --repo 확인
+5. 필요한 S4에서 stale 그림 2개만 rerender/review
+6. 지정 subagent로 S5
+7. --repo evidence gate 재실행
+8. 지정 subagent로 S6
+9. --repo evidence gate 재실행
+10. 독립 fact-reviewer
+11. S7은 Studio 요청이 없으므로 SKIP
+12. verify-pipeline-run.py
+13. keycloak project gates
+14. 전체 verify-pipeline.py
+15. 전체 unittest
+```
+
+---
+
+# 9. 최종 판정
+
+현재 결과물의 **내용 품질 자체에는 추가 리뷰 finding이 없다.**
+
+하지만 7단계 하네스 준수를 완료 조건으로 보는 현재 프로젝트 기준에서는 다음 두 가지가 실제 완료 차단이다.
+
+1. subagent isolation을 실제로 수행하지 않은 current remediation run
+2. `--repo`가 빠진 S3/S5/S6 evidence gate
+
+그리고 SVG 2개의 stale manifest도 정리해야 한다.
+
+따라서 현재 상태는:
+
+> **keycloak = 아직 더 봐야댐**
+
+이 세 범위가 닫힌 뒤에만 Keycloak을 **완료**로 바꾸고 다음 프로젝트로 넘어간다.