docs(session-mcp-tool-surface): kubectl 을 걷은 근거를 「이 표면에 두지 않는 것」에 세운다 (기각)

[dlddu-k3s-homelab-k3s-mcp]

정합성 작업 rct_20260913-0001 · 모델 tbm_session-platform-mcp-tool-roadmap

무엇이 비어 있었나

#134가 등재 4번 kubectl을 걷으면서 걷은 근거를 적지 않았다. 그 PR은 그 공백을 숨기지 않고 문서 머리에 현재형으로 남겼다:

걷은 근거는 아직 이 문서에 없다 — 「이 표면에 두지 않는 것」으로 판정된 것인지 뒤로 미룬 것인지가 열려 있고, 그 판정이 서면 해당 절에 한 줄로 들어갈 자리다

이 문서를 to-be로 갖는 모델은 철회를 「⑵ 근거와 함께 등재에서 철회」로만 인정하고, 그 정의가 「철회라면 근거를 「이 표면에 두지 않는 것」 절에 남긴다」로 자리까지 지정한다. 그 판정을 세운다.

⚠️ 이 결함에는 재감지 경로가 없다. 모델의 to-be 버전 스크립트는 「다음에 구현할 도구」의 ### 헤딩 목록만 읽는데, 근거 한 줄은 다른 절에 들어가므로 그것을 적어도 roadmap:4는 한 글자도 움직이지 않는다. kubectl은 이미 목록 밖이라 이 축을 다시 깨울 버전 이동도 없다 — 지금 잡지 않으면 영영 보이지 않는다.

판정: 기각(미룸이 아니다)

항목 제목을 개별 도구가 아니라 기준으로 지었다 — 「게이트 밖에 남는 권한을 요구하는 도구」. 호출 하나하나가 승인을 지나도, 그 도구를 쓸모 있게 만들려고 넓힌 상시 권한은 승인이 회수하지 못한다. 넓히는 그 권한이 곧 도구의 고유 가치인 항목은 이 표면에 두지 않는다.

kubectl이 그 기준에 걸리는 근거는 전부 이 레포에서 실측했다.

#	관측	근거
⑴	자리 자체는 맞았다 — 워크로드 파드는 data-plane SA 토큰을 갖지만 AC-F2의 egress 허용 목록(kube-dns·자기 헬퍼)이 API 서버로 가는 길을 끊고, 헬퍼 파드는 길은 있으나 Kubernetes 신원이 없다	helperPodSpec은 ServiceAccountName을 주지 않고 automount를 끈다. 그 코드 주석이 이유를 **「nothing in it needs the API server, and the pod holds both of the platform's external secrets」**로 적는다
⑵	kubectl의 고유분 = RBAC 확대분 — 그 SA가 갖는 것은 view + 노드 읽기뿐이라 apply·exec가 애초에 되지 않는다. 조회 쪽은 등재 2번(K3s MCP 재노출)이 도구별로 좁은 승인 컨텍스트에 실어 내므로(R4상 그쪽이 낫다는 것은 등재 당시 이미 적혀 있었다), 남는 고유분이 정확히 「되게 하려고 넓히는 권한」이다	k8s/data-plane-rbac.yaml (view + …-node-reader; 그 파일 주석이 「RBAC은 additive라 Secrets를 뺀 와일드카드를 안전하게 표현할 수 없다」고 적는다)
⑶	그 SA는 approval-gated 전용이 아니다 — 워크로드 파드 스펙은 타입 공통이고 ServiceAccountName=data-plane · automount true인데, NetworkPolicy 2종과 승인 게이트는 workloadType == approval-gated 분기 안에서만 붙는다. 게이트 뒤에 도구 하나를 세우려고 넓힌 권한이, 게이트도 egress 정책도 없는 shell·claude-code 워크로드 파드에 그대로 열린다	client_orchestrator.go — 워크로드 파드 스펙(타입 공통) vs applySessionNetworkPolicies 호출 위치
⑷	전용 자격 증명으로 ⑶의 누출을 피해도 그 신원이 앉을 자리는 플랫폼의 외부 Secret 둘을 이미 다 든 헬퍼 파드다	AC-F6의 분리가 막으려는 형태 그 자체

미룸이 아니라 기각인 이유는 ⑶·⑷다 — 선행(R9 + AC-F4 개정)을 하나 더 치르면 열리는 문이 아니라, 치르고도 승인이 통제하지 못하는 권한이 남는다. 등재 당시 적혀 있던 「넓힌 권한은 게이트가 거절해도 남는다」의 실체가 이것이고, #134가 걷은 판단은 옳았다.

영구 봉인이 아니다 — 재진입 조건

이 문서의 선례를 그대로 썼다. R10의 사설 CA 자리가 「수요 0이라 반려됐다(2026-09-07) … 그 판정을 먼저 뒤집어야 한다」로 서 있다. 같은 형태로:

임의 리소스·apply·exec 수요가 실제로 서면 먼저 위 2번의 범위 확장으로 다루고, 그것으로 부족함이 관측되면 그때 이 판정을 뒤집는다.

그리고 새 기준이 등재 2번을 잘못 잡지 않도록 비적용 단서를 함께 뒀다 — 2번이 요구하는 토큰의 힘은 게이트를 지나는 도구 밖에서 행사되지 않고, 이미 다른 파드가 들고 있는 권한을 넓히지도 않는다.

변경

docs/session-mcp-tool-surface.md 한 파일, +20/−2.

1. 「이 표면에 두지 않는 것」 절 끝에 네 번째 항목(위 판정). 항목 3 → 4.
2. 머리 변경 이력의 2026-09-13 항목에서 거짓이 된 두 줄을 정정(4줄 → 4줄, 순증 0). 새 날짜 항목을 만들지 않았다 — #135가 2026-09-13 (2) 라벨을 이미 쓰고 있어 새로 만들면 번호가 충돌하고, 이 변경은 그 항목이 스스로 비워 둔 자리를 채우는 것이라 같은 항목 안이 제자리다(선례: #134가 2026-09-12 (2) 항목의 낡은 「1~4」를 같은 방식으로 고쳤다).

코드 0줄 · docs/index.html 0줄(메타 「도구 추가 규칙 12 · 다음 구현 대상 4」는 이 변경으로 움직이지 않는다).

불변 증명

base 69ff764와 이 브랜치에서 각각 돌려 출력이 바이트 동일함을 cmp로 확인했다.

대상	결과
모델 to-be 버전 스크립트	roadmap:4 0. ping|1. git_clone|2. K3s MCP 재노출|3. gh CLI — 불변
모델 as-is 버전 스크립트	tools:1 web_fetch_get — 불변
scripts/check_comment_policy.py	바이트 동일 (판정 완료 2989줄 / 등재 범위 14) — 주석을 한 줄도 더하지 않았다
scripts/check-fidelity-allowlist.py	바이트 동일
scripts/check-render-fidelity.py	바이트 동일
scripts/e2e/check-scenario-mapping.sh	바이트 동일 (시나리오 37 = 매칭 0 + 예외 3 + 유예 34 + 공백 0)

두 버전이 다 불변인 것이 이 task의 정상 상태다 — 완료 기준을 버전 이동으로 잡지 않았다. 애초에 그 축에 재감지 경로가 없다는 것이 이 task가 열린 이유다.

충돌면 — #135와 두 자리

열린 PR 여섯(#106 · #127 · #130 · #131 · #133 · #135) 중 이 파일을 건드리는 것은 #135 하나다. 겹치는 자리 둘 다 산문이고 해소가 기계적이다.

• 머리 변경 이력 — #135는 …자리다)*. 줄을 …자리다) ·로 바꾸고 2026-09-13 (2) 항목을 잇는다. 이 PR은 그 두 줄을 정정한다. → 해소: 정정된 문장을 살리고 그 뒤에 #135의 (2) 항목을 잇는다(기각으로 섰다 — 뒤로 미룬 것이 아니라는 판정까지 그 항목이 갖는다) · + #135의 블록).
• 「이 표면에 두지 않는 것」 — #135는 두 번째 항목(게이트를 지나지 않는 도구)의 예외 지시어를 「위 0번」에서 「위 표의 ping」으로 바꾸고, 이 PR은 네 번째 항목을 끝에 더한다. 서로 다른 항목이라 양쪽을 그대로 두면 된다.

범위 밖 (후속)

• 🔜 등재 1~3의 미착지 — 전부 R9(AC-F6 자격 증명 배치 개정)가 선행이다.
• 🔜 0번 ping 착지 — 자매 rct_20260912-0001 / #135가 들고 있다.
• docs/doc-tracker.md 행 없음 — 선례 docs(session-mcp-tool-surface): 진단 도구 ping 을 0번으로 등재한다 (구현 대상 4→5) #128·docs(session-mcp-tool-surface): kubectl 을 구현 대상에서 걷는다 (구현 대상 5→4) #134 둘 다 등재 변경에 원장 행을 두지 않았다. 걷힌 항목이 들고 있던 관측은 그 원장의 2026-09-08 (2) 행에 history로 남아 있고, 이 PR은 그중 판정에 쓰이는 것만 살아 있는 절로 옮겼다.

🤖 Generated with Claude Code