feat(skills): finding-unknowns를 Codex에도 노출 — 동등 지휘자 + 행동 계약 중립화

[greenheadHQ]

Summary

• finding-unknowns(미지 방법론 오케스트레이터)를 Codex에도 노출해 동등 지휘자로 만든다 — Codex 단독 세션도 구현 전(정찰·blindspot·인터뷰·계획)부터 구현 후(퀴즈)까지 풀사이클을 지휘할 수 있다.
• 도구명 리터럴과 runtime-mapping 링크를 제거하고 행동 계약("blocking 질문 도구로 한 문항씩 답을 기다리고, 가정하고 진행 금지")만 남기는 중립화를 함께 수행한다.

기존 문제/배경

PR #1082는 finding-unknowns를 Claude 전용으로 신설하며 Codex를 intentionallyNotExposed에 두었다. 당시 근거는 "지휘 대상인 grilling·prototype이 Codex에 없다"였는데, 이 전제가 실측으로 반증됐다: Codex의 user 스코프 스킬 경로는 ~/.codex/skills가 아니라 ~/.agents/skills이며(upstream 문서 확인), npx로 설치된 Matt Pocock 스킬들이 정확히 그 경로에 있어 맥북·miniPC 양쪽 Codex 세션에서 이미 발견된다 (codex exec 스킬 목록 probe + ssh 실측). 남은 장애물은 노출 목록과 Claude 전용 도구 리터럴뿐이었다.

CIR (Change Intent Record)

• v1 (PR feat(skills): finding-unknowns — 지도-영토 미지 방법론 오케스트레이션 스킬 #1082): Codex 비노출 — "오케스트라(grilling·prototype)가 Codex에 없다"는 판단. 사용자 스크린샷($grilling이 Codex에 노출됨)으로 반증됨.
• v2 (이번 변경, grilling 세션 합의): ① 분업 모델 = 완전 동등 지휘자 (구현 국면 한정·읽기 전용 참조안 기각), ② 중립화 = 행동 지시만 유지 — 도구명 리터럴·매핑 링크 제거안과 전부 제거안 중, "Codex default mode는 make-assumptions-and-only-stop-if-blocked 정책이라 질문 도구를 자동 호출하지 않는다"는 실측(configuring-codex 0.144.1 기록, run-da 선례) 때문에 행동 계약 한 줄은 유지, ③ PR 스코프 = feat(skills): finding-unknowns — 지도-영토 미지 방법론 오케스트레이션 스킬 #1082 머지 후 별도 PR (한 PR에 얹는 안 기각 — 리뷰 3라운드 수렴 완료 상태 보존).

trade-off: 도구명 힌트가 사라져 각 런타임이 자기 질문 도구를 스스로 찾아야 하지만, 사용자 실측대로 현행 모델은 "질문해"라는 행동 지시만으로 올바른 도구를 찾는다. 반면 "멈춰서 물어라"는 성향 보정은 도구명과 무관하게 필요해 행동 계약으로 남겼다.

ADR

대안	설명	장점	단점	결정
행동 계약만 유지	도구명·매핑 링크 제거, "blocking 질문 도구로 한 문항씩, 가정 직진 금지"만	도구 개명에 강건 + Codex 성향 회귀 차단	도구명 힌트 부재	✅
전부 제거	"질문한다"까지만 기술	가장 간결	plain-text 퇴행·가정 직진 위험 (P1 리뷰에서 직접 지적된 실측 리스크)	❌
매핑 링크 유지	runtime-mapping 참조 존치	가장 보수적	사용자 방침(도구 지식은 모델에 위임)과 배치, SoT 참조 관리 비용	❌

구현 상세

파일	변경	내용
modules/shared/programs/codex/default.nix	수정	intentionallyNotExposed → exposedCodexSkills 이동 (실측 근거 주석)
scripts/ai/verify-ai-compat.sh	수정	EXPECTED_EXPOSED 이동, SHARED_EXPOSURE_EXCLUDE·SKILL_NEUTRAL_LINT_EXCLUDE에서 제거 (도구-중립 lint 편입)
skills/finding-unknowns/SKILL.md	수정	인터뷰·게이트 A에 blocking 질문 행동 계약 + "침묵을 동의로 간주 금지" + grilling/prototype 미설치 환경 요지 폴백
skills/finding-unknowns/references/tactics.md	수정	퀴즈 출제 규칙에서 도구명 리터럴·매핑 링크 제거 → 행동 계약
skills/finish-pr/SKILL.md	수정	퀴즈 게이트 2항의 매핑 링크 제거 → 행동 지시

참고 레퍼런스

• PR feat(skills): finding-unknowns — 지도-영토 미지 방법론 오케스트레이션 스킬 #1082 — finding-unknowns 신설 (이번 변경이 뒤집는 "Claude 전용" 결정의 출처)
• Codex 스킬 발견 경로 문서 — user 스코프 = ~/.agents/skills 확인
• .claude/skills/configuring-codex/SKILL.md — "default mode 모델은 질문 도구를 자동 호출하지 않으므로 본문 명시 지시 필요" 실측 기록 (행동 계약 유지 근거)

Human Test Plan

정상 동작 검증

1. main 머지 + nrs 후 ls -la ~/.codex/skills/finding-unknowns를 실행한다.
   • 기대: 레포 소스를 가리키는 심링크 존재.
   • 실패 시: codex default.nix의 exposedCodexSkills 항목과 home-manager 재활성화 확인.
2. ./scripts/ai/verify-ai-compat.sh를 실행한다.
   • 기대: 완전 통과 — finding-unknowns가 노출 정합성 검사와 도구-중립 lint를 (exclude 없이) 통과.
   • 실패 시: lint FAIL이면 스킬 본문에 도구 리터럴 잔존 여부 grep.
3. nixos-config에서 Codex 세션을 열고 $finding-unknowns를 입력한다.
   • 기대: 스킬이 선택기에 노출되고 로드된다.
   • 실패 시: codex exec로 스킬 목록 probe 후 ~/.codex/skills 인식 여부 확인.

행동 계약 검증

4. Codex 세션에서 finding-unknowns를 발동해 장기작업 킥오프를 시킨다.
   • 기대: 인터뷰·게이트 A 확인이 request_user_input(blocking) 호출로 이뤄지고, plain-text 질문 후 가정 직진하지 않는다.
   • 실패 시: SKILL.md 게이트 A·인터뷰 문구의 행동 계약 재확인 (도구명 없이도 blocking 호출을 하는지가 이 설계의 검증 포인트).

Negative·Regression

5. grep -rn "AskUserQuestion\|runtime-mapping" modules/shared/programs/claude/files/skills/finding-unknowns/를 실행한다.
   • 기대: 0건 (리터럴·매핑 링크 부재).
6. Claude 세션에서 방법론 적용 PR의 finish-pr 퀴즈 게이트가 기존과 동일하게 동작한다 (feat(skills): finding-unknowns — 지도-영토 미지 방법론 오케스트레이션 스킬 #1082 머지 시 4/4 통과 실적과 같은 흐름).
   • 실패 시: finish-pr 2항의 행동 지시 문구 확인.

---

https://claude.ai/code/session_01PbbrsHKxkzkaKn9iJdgYDH

Summary by CodeRabbit

• 문서 개선
  • finding-unknowns의 단계별 지침(생략 사유 기록, 무단 생략 금지)과 예외 처리 기준을 구체화했습니다.
  • 인터뷰/게이트 A에서 질문은 답을 기다리는 방식으로 진행하고, 침묵을 동의로 보거나 “막히지 않음”으로 가정하지 않도록 규칙을 강화했습니다.
  • finish-pr의 퀴즈 게이트 질문 진행 문구를 정리해 일관성을 높였습니다.
• 호환성 개선
  • finding-unknowns의 환경별 노출/검증 정책을 정비해 shared 스킬로 처리되도록 조정했습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 63b6fb41-76c9-4211-995e-87d3740ab7ee

📥 Commits

Reviewing files that changed from the base of the PR and between 77e6591 and fd5de41.

📒 Files selected for processing (1)

• modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.md

✅ Files skipped from review due to trivial changes (1)

• modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.md

---

📝 Walkthrough

Walkthrough

finding-unknowns의 구현 전·퀴즈 게이트 지침과 Codex 공유 노출 및 호환성 검증 정책이 변경됐다.

Changes

finding-unknowns 실행 및 호환성 정비

Layer / File(s)	Summary
질문 게이트와 실행 지침 강화 modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.md, modules/shared/programs/claude/files/skills/finding-unknowns/references/tactics.md, modules/shared/programs/claude/files/skills/finish-pr/SKILL.md	구현 전 단계의 스킵·위임 조건과 blocking 질문 규칙을 명확히 하고, 답을 가정하지 않는 퀴즈 게이트 지침으로 정리했다.
공유 스킬 노출 및 린트 검증 변경 modules/shared/programs/codex/default.nix, scripts/ai/verify-ai-compat.sh	finding-unknowns를 Codex 공유 스킬 및 예상 노출 대상으로 포함하고, 공유 노출·도구 중립성 lint 제외 목록에서 제거했다.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• greenheadHQ/nixos-config#520: 공유 스킬의 Codex 노출 및 검증 목록을 조정한다.
• greenheadHQ/nixos-config#623: verify-ai-compat.sh의 스킬 도구 중립성 lint 제외 정책과 관련된다.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	finding-unknowns를 Codex에 노출하고 런타임별 계약 표현을 중립화한 मुख्य 변경을 정확히 요약합니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/finding-unknowns-codex

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.md`:
- Line 44: finding-unknowns 스킬의 저위험 미지 처리 규칙을 Gate A 조건과 일치시키세요. 사용자가 “라벨된 가정과
함께 진행”을 명시적으로 허용하기 전에는 기본값을 적용해 구현을 진행하지 말고, 해당 기본값은 제안하고 기록만 하도록 수정하세요.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 477203aa-2b3e-44a3-9b98-72dc4423f657

📥 Commits

Reviewing files that changed from the base of the PR and between fd9253f and 77e6591.

📒 Files selected for processing (5)

• modules/shared/programs/claude/files/skills/finding-unknowns/SKILL.md
• modules/shared/programs/claude/files/skills/finding-unknowns/references/tactics.md
• modules/shared/programs/claude/files/skills/finish-pr/SKILL.md
• modules/shared/programs/codex/default.nix
• scripts/ai/verify-ai-compat.sh

[greenheadHQ]

머지 후 검증 결과

• merge: squash aa15b082 (--match-head-commit fd5de410 고정), main 최신화 완료
• 퀴즈 게이트: 3문항 출제 → 전 문항 정답 통과 (문항 1·3 오답 → 설명 → 재출제 흐름 작동)
• nrs: 성공 (55s) — ~/.codex/skills/finding-unknowns 심링크 생성 실측 (SKILL.md·references 접근 가능)
• ./scripts/ai/verify-ai-compat.sh: 완전 통과 — finding-unknowns가 이번엔 SKILL_NEUTRAL_LINT_EXCLUDE 없이 도구-중립 lint를 통과 (노출 정합성 오라클 포함)
• Codex 런타임 인식 probe (Human Test Plan 3): 환경 제약으로 미수행 — codex usage limit 도달 (try again at Jul 12th 12:01 AM). 대체 확인: 동일 메커니즘(~/.codex/skills 심링크)의 기존 9종 인식은 노출 전환 전 probe에서 기실측. Human Test Plan 3·4번(Codex 세션 $finding-unknowns 노출 + blocking 질문 행동)은 limit 해제 후 사용자 확인 항목으로 남김.