donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
805a18f486d651118e3b324e583839e00822e545
document-haness/reviews/2026-09-20-keycloak-final-verification-review.md
T

11 KiB
Raw Blame History

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:

17 runs
17/17 verify-pipeline-run.py PASS
schemaVersion = 4

수정된 17개 Record와 17개 current run의 record mapping도 일치한다.

2.2 Keycloak 프로젝트 검사

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 전체를 다시 검사했다.

Natural Prose: PASS 24/24
Voice:         PASS 24/24
Command:       PASS 24/24

Keycloak 기록에는 shell/CLI block이 없으므로 command lane은 정상적으로 N/A다.

2.4 전체 회귀

verify-pipeline.py
exit 0

전체 테스트:

Ran 391 tests
OK (skipped=14)

3. F-01 — current remediation이 실제 subagent 분리 계약을 충족하지 않음

등급: 완료 차단

현재 하네스는 단순히 역할 이름을 원장에 적는 것이 아니라 각 단계마다 정해진 subagent를 별도로 실행하는 구조다.

running-tech-log-pipeline/SKILL.md와 stage-contracts.md는 다음을 요구한다.

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개 모두 다음 사실이 직접 기록돼 있다.

별도 Agent tool은 노출되지 않아 current remediation 세션이
fact-reviewer 계약을 직접 수행했다.

즉 원장의:

"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는 명확히 다음 명령을 요구한다.

node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs <프로젝트> --repo

S5와 S6도 문장 수정 이후 S3 gate를 다시 실행하는 계약이다.

하지만 17개 current remediation run을 전부 확인하면 S3/S5/S6가 다음 형태로 기록되어 있다.

node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs keycloak

즉 --repo가 빠져 있다.

결과:

missing --repo:
17/17 runs
S3, S5, S6 모두

이 차이는 단순 옵션 차이가 아니다.

현재 올바른 계약 명령을 직접 실행하면:

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를 현재 머신에서 실제로 접근 가능하게 만드는 것이다.

현재 정본 경로:

/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하지만 다음 경고가 남아 있다.

SSOT 문맥이 바뀐 뒤 그림을 다시 보지 않았다

- ap1-direct-architecture
- login-api-phase-split

현재 두 TechViz context.json / spec.json은 새 SSOT hash를 가리킨다.

current document/context sha256
ea10df24b892e2c57123a37a4b4f0d821e4f394353e6746f50df6a48342353e9

하지만 두 asset manifest는 이전 source context hash를 계속 갖고 있다.

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한다.

대상:

ap1-direct-architecture
login-api-phase-split

그 뒤:

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:

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은:

UNVERIFIABLE

이다.

이를 PASS라고 쓰면 안 된다.

다만 문서 본문 자체의 기존 수정 사항은 SSOT / local evidence 기준으로 재검토했고 새로운 내용 오류는 찾지 못했다.

7. 현재 완료 조건

내용 / 문체 / SVG 구조

  • 기존 리뷰의 문서 내용 finding 반영
  • Bearer JWT validation chain SVG
  • IdP Brokering SVG
  • Natural Prose 24/24 PASS
  • Voice 24/24 PASS
  • Command 24/24 PASS
  • Figure Text PASS
  • Figure Overlap PASS
  • Figure Provenance PASS
  • Required Content PASS
  • Tree PASS
  • 전체 pipeline exit 0
  • 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개만이다.

순서:

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을 완료로 바꾸고 다음 프로젝트로 넘어간다.

Reference in New Issue View Git Blame Copy Permalink