docs(AC-F6): 자격 증명 금지의 축을 「타입 전체」에서 「워크로드 파드」로 좁힌다 (등재 2번의 첫 작업)

[dlddu-k3s-homelab-k3s-mcp]

이 PR이 닫는 gap

reconciler task tbm_session-platform-mcp-tool-roadmap / rct_20260914-0001.

docs/session-mcp-tool-surface.md의 「다음에 구현할 도구」 등재 2건(2. K3s MCP 재노출 · 3. gh CLI)이
표면에 서지 않은 상태다. 둘 다 MCP 컨테이너에 게이트웨이 3종 밖의 자격 증명을 요구해 R9에 걸리고,
그 문서는 스스로 **「그 차이를 AC-F6에 적는 것이 2번의 첫 작업이고, 도구 코드는 그다음이다」**라고 지시한다.

이 PR은 그 첫 작업만 한다 — 문서 셋만 바뀌고, 도구 코드도 실제 Secret 배치도 없다.

무엇이 바뀌나

docs/prd/approval-gated-workload.md AC-F6의 산문 한 자리가 금지를 타입 전체로 적어 두어
(「k3s-mcp-token과 런타임 plugin 부트스트랩은 이 타입에 두지 않는다」), 2026-09-03 확정이 스스로
명시한 대가(「필요해지면 세션 MCP에 다시 실어야 한다」)를 이행할 경로 자체가 막혀 있었다.

금지의 축을 파드로 좁힌다. 헬퍼 파드의 MCP 컨테이너는 아래 네 조건을 전부 만족하는 한
게이트웨이 3종 밖의 자격 증명을 받을 수 있다.

	조건
C1	파드·컨테이너 경계 — MCP 컨테이너에만. 워크로드 파드에도, 같은 파드의 credential-proxy에도 두지 않는다
C2	에이전트가 게이트 밖에서 그 힘에 닿지 못함. 판정 기준은 「누가 값을 들고 있는가」가 아니라 「에이전트가 게이트 없이 닿을 수 있는가」 — 헬퍼 컨테이너 안에서만 쓰이고 에이전트에게 경로를 만들지 않는 플랫폼 내부 사용은 조건 안이다
C3	다른 파드가 이미 가진 상시 권한을 넓히지 않는다(승인이 회수하지 못하고, 게이트 없는 타입에도 열린다)
C4	세션 조회·로그·read·SSE·승인 컨텍스트 어디에도 노출되지 않는다

바뀌지 않는 것

• 워크로드 파드의 보장 — 한 글자도 줄지 않는다. 어떤 외부 자격 증명도 받지 않고,
  K3S_MCP_TOKEN을 보면 에이전트가 기동을 거부하는 단언(validateApprovalGatedClientEnv)과
  검증 항목 (c)가 그대로 남는다. 좁힌 것은 산문의 적용 범위이지 워크로드 파드의 보장이 아니다.
• AC-F2 — 한 줄도 건드리지 않았다. 2026-09-03에 기각한 대안 ③은 뒤집히지 않았다:
  ③은 워크로드 파드의 egress 허용 목록을 넓혀 주 컨테이너가 직접 나가게 하는 것이었고,
  이번에 더해지는 것은 egress가 아니라 헬퍼 파드 안의 자격 증명 하나다(헬퍼 파드의 egress는
  애초에 정책이 없다 — R12).
• ①(런타임 plugin 부트스트랩을 두지 않는다) — 그대로다. 이 PR은 ①↔②를 건드리지 않는다.
• 등재도 도구 표면도 — 등재 2 · 표면 3 그대로. 연 것은 자리뿐이고 자격 증명도 도구도 배치하지 않았다.

⚠️ 열려 있는 PR #106과 같은 결정을 건드린다 — 머지 전 확인 필요

#106 (feat/approval-gated-plugin-seed)이 같은 AC-F6 확정을
①→②로 뒤집으면서 k3s-mcp-token을 같은 MCP 컨테이너에 들여놓는다. 세 문서가 전부 겹친다.

• 실질은 직교한다 — #106은 plugin 부트스트랩 축(seed로 skills를 나른다), 이 PR은 자격 증명 축
  (금지 범위를 파드로 좁힌다). #106이 넣는 토큰은 seed 전용이고 tools/list에 도구를 하나도 내지 않으므로,
  위 C2가 명시적으로 그 형태를 조건 안에 둔다(플랫폼 내부 사용). 두 결정은 공존 가능하다.
• 문면은 충돌한다 — 둘 다 AC-F6의 같은 문단·같은 확정 항목 영역과 R9·등재 2번 bullet을 고친다.
• #106은 현재 dirty(main과 충돌)이고 2026-09-08 트리 기준이다 — 그 diff는 등재가 아직 4건이고
  1. git_clone이 미착지인 로드맵을 전제한다(feat(session-mcp): 진단 도구 ping 을 표면에 세운다 (등재 4→3) #135·docs(session-mcp-tool-surface): kubectl 을 걷은 근거를 「이 표면에 두지 않는 것」에 세운다 (기각) #136·#140이 그 사이에 2건으로 줄였다). 참조하는
  docs/comment-policy.md도 지금은 docs/comment-policy/README.md다.

판단이 필요한 자리: ⑴ 이 PR을 먼저 머지하고 #106이 그 위로 리베이스하며 ②를 C1~C4 위에 얹을지,
⑵ #106을 먼저 되살리고 이 PR이 그 위로 리베이스할지. 어느 쪽이든 등재 2번이 요구하는 도구 코드는
여전히 남는다 — #106은 seed에서 mcpServers를 제거하므로 K3s MCP 도구는 표면에 서지 않는다.

r2 (2026-09-21) — 리뷰 거부 사유 반영: 사라진 docs/doc-tracker.md 위에 선 준비물을 새 구조로 옮겼다

리뷰(2026-09-20T22:46Z)가 막은 것은 방향이 아니라 없어진 파일 위에 선 준비물이었다 — base e741586 이후
main(#148, 95cfbca)이 docs/doc-tracker.md를 삭제하고 docs/doc-tracker/(index.md + 2026-06~2026-09.md)로 갈랐다.

• 리베이스: origin/main(200230f) 위로 cherry-pick. 실측으로 옮긴 자리 둘 — ⑴ 「✅ 해결된 설계 결정」의 AC-F6 항목은
  docs/doc-tracker/2026-09.md(L68)가 물려받았다(index.md는 월 요약표뿐) → 개정 각주를 거기에 붙였다. ⑵ 변경 이력 표는
  같은 파일의 「이번 달 변경 이력」이고 새 행은 표 끝(2026-09-19 행 뒤)에 붙는 것이 맞다 → 거기에 붙였다.
  나머지 두 파일은 main이 각각 +3/−3으로 doc-tracker.md → doc-tracker/ 경로 문자열만 고쳤고 hunk 충돌 없이 얹혔다.
• 이 PR이 더하는 산문에 옛 경로(doc-tracker.md) 인용은 0건이다(git diff origin/main | grep '^+' | grep doc-tracker.md 빈 출력).
• 날짜를 착지 시점으로 재기입: 확정 항목·선행 해소·이력 행의 2026-09-14 → 2026-09-21(11곳, main에는 그 문자열이 0건이라 전부 이 PR 것).
  이력 행에 PR 번호(docs(AC-F6): 자격 증명 금지의 축을 「타입 전체」에서 「워크로드 파드」로 좁힌다 (등재 2번의 첫 작업) #144)를 붙였다.
• 정적 게이트 4종을 리베이스한 트리에서 다시 돌렸다 — 전부 exit 0. 두 versionScript도 재실행: tools:3 git_clone,ping,web_fetch_get ·
  roadmap:2 2. K3s MCP 재노출|3. gh CLI — main과 바이트 동일(이 슬라이스의 불변식).
• 관문 feat(approval-gated): skills-only plugin seed로 AC-F6 확정을 ①에서 ②로 뒤집는다 #106: 여전히 OPEN·DIRTY(2026-09-12 이후 커밋 0) → 진행 조건 유지.
• 자매 겹침 재실측: docs(tracker): 「외부 도구 web_fetch_get 하나」 사본을 걷고 정본을 가리킨다 (#146 승계 · 월별 폴더) #149(docs-impl r2, CLEAN)가 docs/doc-tracker/2026-09.md에 같은 표 끝 2026-09-21 행 하나를 더한다 →
  add/add 충돌 예정(merge-tree 실측) → 실제로 #149가 먼저 착지(d130521)해 리베이스했다: 양쪽 행 보존, docs(tracker): 「외부 도구 web_fetch_get 하나」 사본을 걷고 정본을 가리킨다 (#146 승계 · 월별 폴더) #149 행이 위, 이 PR의 행은 2026-09-21 (2). 리베이스 뒤 게이트 4종·versionScript 둘 재실행 — 전부 동일. docs(comment-policy): 15차 재판정이 유지로 닫은 사본 11줄을 ② 근거로 걷는다 (등재 61→50 · #143 승계) #150·#130은 겹침 0.
  feat(approval-gated): AC-F5 후반 — 공유 볼륨을 파일시스템 아카이브에 실어 동결·복원을 건너 나른다 #127·#106은 옛 doc-tracker.md를 고치므로 어차피 자기 리베이스 몫.

검증

• 버전 스크립트 불변 확인 — to-be(등재 ### 헤딩)를 재실행: roadmap:2 2. K3s MCP 재노출|3. gh CLI
  (변화 없음). as-is(toolDefinitions)는 코드를 건드리지 않아 tools:3 그대로.
• 정적 게이트 4종 로컬 통과 — check-fidelity-allowlist.py · check-render-fidelity.py ·
  check_comment_policy.py · e2e/check-scenario-mapping.sh 전부 OK.
• 사본 정합 — docs/test/approval-gated-workload.md의 AC-F6 기대 결과는 이미 「이 타입의 워크로드
  파드에 주입되지 않고」로 적혀 있어 개정 후에도 참이다(손대지 않았다). docs/doc-tracker/2026-09.md의 해결된
  설계 결정 사본과 변경 이력은 이 PR이 함께 갱신했다(r2에서 월별 폴더로 이관).

범위 밖 (후속)

• 등재 2번의 도구 코드 — K3s MCP 도구를 도구별 게이트 위임으로 내는 일. 그 슬라이스가 C1~C4 충족을
  보이며 Secret을 실제로 배치하고, pod 스펙과 검증 (c')를 함께 움직인다. 읽기부터가 정합(R4).
• 등재 3번(gh CLI) — R4 승인 화면이 이 레포 밖이라 별건.
• data-plane/README.md가 세션 MCP를 「offers one external tool, web_fetch_get」으로 적는다 —
  git_clone·ping 착지 뒤 낡았다. 이 PR의 축이 아니라 손대지 않았다.

---

🤖 Generated with Claude Code