v1.21.0

Fixed

• HTML 네 스킬(/eli5, /explain-diff, /micro-world, /visual-doc) 한글 줄바꿈 개선: 실제 산출물 피드백 반영. (1) 영문·숫자·코드 칩 뒤의 조사를 띄어 써서(Job 은, </code> 을, 문서 하나에 70곳) word-break:keep-all에서도 조사가 줄 첫머리에 오던 문제. 네 SKILL.md에 조사와 어미를 앞말에 붙여 쓰는 공통 규칙과 조사 앞 공백 grep 검사를 추가. (2) 한 / 번처럼 수량 표현이 줄 끝에서 갈라지던 문제. 숫자와 단위는 붙여 쓰고 수 관형사와 단위 사이에는  를 넣는다. (3) 문단 마지막 줄에 한두 어절만 남던 문제. 네 템플릿의 문단에 text-wrap:pretty 추가 (Firefox는 미지원이라 기본 줄바꿈). (4) eli5 lede만 620px이라 제목·그림·본문(832px)과 오른쪽 끝이 어긋나던 문제. max-width:40em을 없애고, eli5 제목에 text-wrap:balance와 overflow-wrap:anywhere 추가. visual-doc 본문 단락의 keep-all 제외는 그대로 둔다. 근거: docs/decisions/2026-07-visual-doc.md (개정 2026-10-03 3차), docs/decisions/2026-08-eli5.md (개정 2026-10-03)
• /eli5 하단 푸터 삭제와 크기 단계 축소 — 실제 산출물 피드백 반영. (1) frame.html의 .foot 자리 지시문("식별자는 전부 여기에만 적는다")과 그림 규칙("식별자는 캡션이나 푸터로")이 맞물려, 조사한 파일 경로·줄 번호가 페이지 맨 아래에 아홉 줄씩 쌓이던 문제. 도메인 밖 독자는 열어볼 일이 없는 정보이므로 .foot를 삭제하고, 출처와 시점은 스킬 이름만 찍히던 hero eyebrow 한 줄로 옮겼다(studio-pipeline · 2026-09-28 기준). 식별자는 기본적으로 페이지에 넣지 않고, 근거가 된 저장소·커밋·파일 경로는 스킬 종료 시 터미널 보고에 적는다. (2) beat의 결론 문장(.say)이 21px로 부제(19px)보다 커서 제목처럼 보이고, max-width:30em이 컬럼보다 좁아 두 어절짜리 마지막 줄이 남던 문제. .say를 17px로 내리고 폭 제한을 없앤 뒤 text-wrap:pretty를 추가했으며, 균형을 맞춰 메인 제목(3860px → 3044px)·부제(19 → 18px)·beat 제목(26 → 22px)·숫자 카드 값(30 → 26px)·규칙 카드(19/15.5 → 18/15px)를 함께 줄였다. 현재·수정안 비교 페이지로 검토한 뒤 확정. 배경과 근거: docs/decisions/2026-08-eli5.md (eli5 1.0.0 → 1.0.1)

New

• /visual-doc·/eli5 라이트/다크 전환 버튼 추가 — 두 스킬의 산출물은 prefers-color-scheme만 따라서 페이지 안에서 테마를 바꿀 방법이 없었다. 공유받은 사람의 시스템 설정에 따라 다르게 보이고, 캡처할 때도 원하는 쪽을 고를 수 없던 문제. 우측 상단에 .theme-btn(반원 아이콘, 36px)을 두고, 누르면 <html>에 data-theme을 써서 시스템 설정을 양방향으로 덮어쓴다. 다크 토큰은 "시스템 따라가기"(@media 안의 :root:not([data-theme="light"]))와 "버튼"(:root[data-theme="dark"])용으로 두 번 정의하고 color-scheme:dark를 함께 지정해 폼 컨트롤·스크롤바도 따라오게 했다. 선택은 localStorage에 저장해 첫 페인트 전에 복원하며(같은 브라우저에서 연 다른 문서에도 적용), 저장소 접근이 막힌 환경에서도 버튼 자체는 동작한다. 버튼은 1080px 이상에서 화면에 고정되고, 그보다 좁으면 본문을 가리지 않게 페이지 맨 위에만 놓인다. 인쇄 시 숨김. Chrome headless로 시스템 라이트/다크 × 넓은/좁은 화면 네 조합의 클릭 동작과 렌더를 검증. eli5에는 템플릿 첫 스크립트가 들어간다 (visual-doc 1.3.1 → 1.4.0)
• /explain-diff·/micro-world 다크 모드 지원과 전환 버튼 — 두 템플릿은 공유 디자인 규칙에 "라이트·다크 양쪽"이 있었는데도 다크 토큰이 없어 시스템이 다크여도 항상 라이트로 나왔다. visual-doc·eli5와 같은 다크 팔레트와 .theme-btn 전환 버튼을 넣고, 규칙 안에 직접 적혀 있던 색(흰 배경 8곳, 흰 글자 4곳, 검정 알파 트랙·그림자)을 새 토큰 --surface·--on-accent·--track·--shadow-sm으로 옮겼다. 다크에서 --blue·--green이 밝아지므로 --on-accent는 어두운 글자로 바뀐다. micro-world의 터미널 패널은 원래 어두운 면이라 두 테마 모두에서 어둡게 유지하되, 다크 페이지 배경과 거의 같은 색이라(대비 1.06:1) 윤곽이 사라지지 않도록 옅은 테두리를 넣었다. 모델이 템플릿 밖에서 직접 쓰는 CSS(explain-diff의 선택적 figure, micro-world의 비터미널 환경 패널)가 한쪽 테마에서만 읽히는 색을 쓰지 않도록 두 SKILL.md에 "색은 전부 토큰에서" 규칙과 확인용 grep을 추가. 수정된 스킬로 실제 문서 두 개를 생성해 라이트·다크 렌더를 확인한 뒤 확정. 배경과 근거: docs/decisions/2026-07-visual-doc.md (explain-diff 1.1.4 → 1.2.0, micro-world 1.0.2 → 1.1.0)
• /eli5 그림 규칙 개정: 구체성 기본값과 텍스트 맞춤 산술 — 실제 사용 피드백 반영. (1) "그림 안 식별자 금지, 독자의 세계로 그리기" 규칙 때문에 기본 산출물이 지나치게 추상적이라 매번 "너무 추상적으로 그리지 마"를 덧붙여야 했다. 구체성을 기본값으로 바꾸고, 상자는 실제 테이블·엔드포인트·플래그를 실제 이름으로 그린 뒤 쉬운 말 한 줄을 붙이도록 했다. 그림 밖에 두는 것은 설명과 파일 경로·줄 번호로 한정. (2) 긴 식별자 라벨이 상자를 넘어 이웃 라벨과 겹치거나 viewBox 밖에서 잘리던 문제. SVG 텍스트는 줄바꿈도 밀어내기도 하지 않으므로, 렌더 없이 그리기 전에 끝나는 산술로 통제한다: 글자당 폭 추정표(한글 1.0em, 영문 소문자 0.6em, 대문자 0.75em, mono 11px 7px, 공백·구두점 4px. Chrome headless 실측보다 보수적), 라벨에서 상자 크기 계산(가장 긴 줄 + 패딩 28, 10 단위 올림, 줄 수 제한 없음), 행 예산(여백 20 + 캡션 열 + 폭 합 + 간격 합 ≤ viewBox, 라벨 화살표 간격 ≥ 라벨 + 24), viewBox 폭 상한 900(세로는 무제한, 상자 수 상한 없음), 선의 상자 관통 금지와 같은 상자에 닿는 선 20px 간격, 텍스트는 도형 뒤에, <svg> 첫 자식에 [40..190] gap45 … 형식의 레이아웃 계획 주석(쓰는 행위가 검산). 산술이 그림 형태를 끌고 가지 않도록 "가리기 테스트"(글자를 가려도 남는 게 없으면 라벨 목록)와 그림 어휘(하나가 여럿이 됨, N회 반복, 같은 것이 돌아옴, 적중/미적중, 선택, 실패, 비용)를 산술 절 앞에 둠. .say는 "그림이 보여준 것의 이름 한 문장"에서 "그림을 읽는 순서·각 부분의 뜻·따라오는 것을 사실로 풀어 쓴 2~4문장(본문 크기)"으로 변경. 걸러내는 것은 소제목의 축어적 반복·비유·번역투이지 설명 자체가 아님. 글씨는 visual-doc 본문 산문과 같은 15px 보통 굵기 보조색. frame.html에 선 위 라벨용 .dg-halo(페이지색 stroke)와 두 줄 상자·계획 주석 예시 추가. 렌더 불가 호스트에서는 Step 5의 잘림·겹침 확인을 이 산술의 재검산으로 대체. (3) 제목·부제목·행 캡션이 beat 역할명(함정, 대가)이나 비유·번역투(세 줄로 읽는 ~, ~의 여정)로 흐르던 문제. 주제의 실제 이름이 들어간 사실 진술로 한정하고 개조식을 허용하며, 비유는 페이지당 한 번 .say에서만. 다른 주제 페이지에 그대로 옮겨도 말이 되는 제목은 너무 추상적이라는 이식성 테스트를 추가. 비유·번역투 금지는 네 HTML 스킬의 공유 디자인 규칙과 AGENTS.md 스킬 공통 규칙으로 올려 모든 스킬 산출물(커밋·PR·이슈 포함)에 적용. (explain-diff 1.2.0 → 1.2.1, micro-world 1.1.0 → 1.1.1, visual-doc 1.4.0 → 1.4.1) 새 규칙만 보고(렌더 금지) 그린 테이블 8개짜리 도식을 Chrome headless로 렌더해 겹침·잘림 없음을 확인. 배경과 근거: docs/decisions/2026-08-eli5.md (eli5 1.0.1 → 1.1.0)
• /eli5 틀 축소와 해설 단일화 — 새 규칙으로 다시 만든 실제 산출물 피드백 반영. hero 여백(88/64 → 44/20)과 제목(3044 → 2430px)·요약(18 → 15.5px)·beat 간격(76 → 48)·소제목(22 → 18px)을 줄이고, 숫자 카드의 값은 phase 1개처럼 말인 경우가 많아 26px 숫자체 대신 16px 굵은 본문으로. 카드 안 figcaption을 없애 해설을 카드 밖 .say 한 문단(2~3문장, 소제목·라벨 반복 금지)으로 단일화. 마지막 규칙 beat는 소제목 + 카드 제목이 같은 말을 두 번 하던 .rule을 소제목 없는 .close 결론 카드로 교체. eyebrow는 출처와 날짜만. 배경과 근거: docs/decisions/2026-08-eli5.md (eli5 1.1.0 → 1.2.0)
• HTML 네 스킬 공통 코드 블록: 구문 강조와 가로 스크롤 — 실제 산출물 피드백 반영. eli5 템플릿에는 코드 블록 컴포넌트가 없어 모델이 <pre>를 즉석으로 만들었고, (1) 모든 토큰이 한 색, (2) 함수 안쪽을 잘라 오며 원본 들여쓰기가 남아 블록 전체가 밀림, (3) 긴 줄이 잘리는데 macOS는 스크롤바를 숨겨 넘친다는 표시가 없음, (4) … 생략 줄이 코드 줄과 구분되지 않음, 네 가지 문제가 있었다. visual-doc·explain-diff의 .codeblock도 단색이었다. 네 템플릿(frame.html, components.html, template.html ×2)에 같은 CSS 블록을 넣고 SKILL.md에 같은 규칙을 추가: 헤더 왼쪽 파일 · 함수, 오른쪽 언어. 공통 들여쓰기 제거(상대 들여쓰기 유지), 생략은 .ln.gap(… N줄 생략, 흐린 기울임체). 구문 강조는 외부 리소스 금지 규칙 때문에 하이라이터 스크립트 없이 모델이 sx-k(키워드)·sx-f(함수)·sx-s(문자열)·sx-n(숫자·상수)·sx-c(주석) span으로 직접 감싼다. 색은 새 값을 만들지 않고 기존 토큰(--violet, --blue, --green, --amber)을 본문 회색과 80% 비율로 color-mix()해 두 테마 모두 차분하게(explain-diff·micro-world에는 없던 --violet 토큰 추가). 긴 줄은 접지 않고 가로 스크롤하며 스크롤바를 항상 보인다(Firefox는 scrollbar-color만 적용). explain-diff diff는 추가·문맥 줄만 토큰 색을 넣고 삭제 줄은 회색으로 눌러 새 코드에 시선이 가게 했으며, +/- 부호만 초록·빨강. explain-diff의 "re-indent 금지" 규칙은 공통 들여쓰기 제거만 허용하도록 완화. 팔레트(4색·2색·5색)·강도(원색·80%·60%)·긴 줄(줄바꿈·스크롤)·diff 처리(전부 색·삭제 줄 회색) 시안을 비교 페이지로 검토해 5색 80%·스크롤·삭제 줄 회색으로 확정. Chrome headless로 네 템플릿 × 라이트/다크 렌더 확인 (eli5 1.2.0 → 1.3.0, explain-diff 1.2.1 → 1.3.0, micro-world 1.1.1 → 1.2.0, visual-doc 1.4.1 → 1.5.0)
• HTML 네 스킬 공통 문장 규칙: 한 대상에 한 이름, 행위자를 주어로, 횟수는 숫자로 — 지금까지의 글 규칙(한 문장 한 생각, 문단 3~4문장)을 지켜도 같은 대상을 액세스 토큰·인증 토큰·세션 키·자격 증명처럼 여러 이름으로 부르거나 거부됐어요처럼 누가 했는지 빠진 문장이 나올 수 있었다. ASD-STE100의 원칙 중 한국어에 옮길 수 있는 세 가지를 네 SKILL.md에 같은 항목으로 넣었다. 문장 길이 숫자 상한은 견본 비교에서 차이가 작아(14 → 11어절) 넣지 않았다.
• /explain-diff 변경 전/후 흐름 그림 — 테마가 호출 주체·순서·횟수를 바꿀 때, 설명과 diff 사이에 같은 경로를 두 줄(변경 전, 변경 후)로 그린 정적 SVG를 넣는다. diff는 바뀐 줄만 보여주고 바뀌기 전에 시스템이 무엇을 했는지는 보여주지 않기 때문이다. diff 블록은 그대로 남는다. 값·이름·타입만 바뀌는 테마에는 넣지 않는다. 템플릿 테마 카드에 FLOW FIGURE SLOT과 .fig·.dg-* CSS 추가.
• /visual-doc 다이어그램 기본값을 손으로 쓴 인라인 SVG로 변경 — mermaid는 자체 테마를 써서 문서의 라이트/다크 전환을 따르지 않고, 특정 선 하나를 강조할 수 없고, 호스트가 그려주지 않으면(HTML 파일을 로컬 브라우저로 열 때) 소스 글자가 그대로 보였다. 이제 흐름·순서·구조 그림은 .card > figure.fig 안의 SVG로 그리고, mermaid는 노드가 대략 15개 이상이라 손으로 배치하기 어려운 다이어그램에만 쓴다. eli5의 그림 규칙과 글자 폭 산술을 visual-doc·explain-diff에도 같은 글로 넣었다 (viewBox 상한만 카드 안 그림의 실제 폭에 맞춰 750·720). eli5의 상한도 같은 기준으로 900에서 840으로 내렸다 (실제 폭 782px에서 900이면 13px 글자가 11.3px로 줄었다).
• /eli5 조작할 수 있는 그림 허용과 세 스킬 공통 조건 — eli5는 조작 요소가 전혀 없었다. 값을 움직여야 요점이 보이는 주제(결과가 값 3개 이상에 걸쳐 달라지거나, 동작이 뒤집히는 경계가 요점)에 한해 페이지당 하나를 허용한다. 두 상태 비교(전/후, 켬/끔)는 조작 요소보다 두 줄짜리 정적 그림이 비교하기 좋으므로 정적으로 그린다. 같은 조건 5항목을 visual-doc·explain-diff의 기존 "입력이 결과를 바꿀 때만" 문구 자리에 넣었다. frame.html에 .ctl·.seg 컨트롤과 예시 스크립트 추가. SVG 안에 <script>를 넣지 않는 규칙은 유지하고, 스크립트는 <body> 끝에 둔다.

---

v1.20.0·v1.20.1 포함 안내: 두 버전은 별도 태그와 Release 없이 이 릴리스(v1.21.0)에 함께 포함됐다. 아래는 CHANGELOG의 해당 섹션이다.

v1.20.1 (2026-09-10)

Fixed

• /explain-diff 구조 트리가 계층 없이 평평하게 나오던 문제 — 실제 산출물 피드백 반영. 템플릿의 트리 행 예시가 ├─ {{PATH}} 한 줄뿐이고 SKILL.md에 중첩 규칙이 없어, 건드린 파일마다 전체 경로(graph/workflows/file_indexing.py, graph/models/llm/utils.py …)를 같은 깊이에 나열해 트리라기보다 파일 목록이 되던 문제. 템플릿을 중첩 예시(디렉토리 행 + │ ├─/└─ 가이드 prefix + 삭제 행)로 교체하고 .guide(gray300, 이름보다 연하게)·.dir(gray700 굵게) 스타일을 추가해 들여쓰기가 먼저 읽히게 했다. SKILL.md에 트리 구성 규칙 명시: 행은 자기 이름만 표시하고 부모 아래 중첩, 가이드 prefix 계산법(형제가 남은 조상은 │ , 닫힌 조상은 공백, 마지막 형제는 └─), 단일 자식 디렉토리 체인·같은 방식으로 바뀐 형제 파일은 한 행으로 접기(config.{prod,beta}.yaml), 디렉토리 행 칩은 디렉토리 전체가 신설·삭제된 경우에만, 디렉토리 우선 알파벳 정렬, 4단계 초과 깊이는 접기 신호. Chrome headless 렌더링으로 검증 (explain-diff 1.1.3 → 1.1.4)

New

• /explain-diff 긴 트리 자동 접기 — 계층 트리로 바뀌면서 디렉토리 행이 추가돼 대형 PR에서는 개요 파트가 트리 카드에 잠식되는 문제. 템플릿 JS가 .tr-row를 세어 20행을 넘으면 .capped를 붙이고 페이드와 나머지 n개 행 펼치기 버튼을 자동으로 단다 (20행 이하 문서는 아무 변화 없음, 스킬이 마크업을 손댈 필요 없음). 펼치기·접기는 max-height를 실측 px 값 사이에서 전환해 부드럽게 움직이고, 펼친 뒤에는 max-height를 풀어 이후 레이아웃 변화에도 잘리지 않게 한다. 접을 때 트리 머리가 뷰포트 위로 벗어나면 기존 섹션 이동 함수로 되돌려 사용자가 위치를 잃지 않게 하고, prefers-reduced-motion이면 즉시 전환. 세로 제한 없이 두는 안(A)과 비교 페이지로 검토한 뒤 채택. 삭제 행의 취소선이 가이드 문자까지 그어지던 문제도 .guide를 inline-block으로 바꿔 함께 수정
• /explain-diff disclosure(details.fold) 스타일 신설 — 실제 산출물에서 트리를 브라우저 기본 <details>로 감싸 ▶ 전체 변경 파일 47개 보기 같은 summary가 템플릿 폰트 규칙을 타지 않고 따로 놀던 문제. 템플릿에 없는 컴포넌트를 모델이 즉석에서 만든 경우로, (1) SKILL.md에 "트리는 항상 로드 시 보이며 <details>나 요약 카드로 대체하지 않는다, 헤더 문구 디렉토리 변화 유지"를 명시하고 (2) 다른 곳에서 접기가 필요할 때를 위해 본문 타이포그래피를 상속하는 details.fold(커스텀 chevron, hover·focus 상태)를 팔레트에 추가

v1.20.0 (2026-09-07)

Changed

• /code-review Codex 통합을 opt-in으로 전환 — 기존에는 Codex plugin companion이 발견되기만 하면 플래그 없이도 adversarial review가 자동 실행됐다. 이제 --codex / --codex-general / --codex-both(또는 "codex도 같이" 같은 명시적 자연어 요청)가 있을 때만 실행하며, 플래그가 없으면 companion 탐색(find)조차 하지 않는다. Codex 활성 여부는 사용자 환경이 아니라 스킬 실행 절차(Step 2.5)가 결정하므로 플러그인 저장소에서 관리한다. --no-codex는 프로젝트 지침·자연어 요청을 덮어쓰는 강제 off 용도로 유지 (code-review 1.10.0 → 1.11.0)
• /code-review Codex Auth Gate 신설 — Codex를 명시적으로 요청한 경우 실행 전에 node "$COMPANION" setup --json으로 .auth.loggedIn을 확인한다. companion이 없거나, Codex CLI가 설치되어 있지 않거나(.codex.available, plugin과 CLI는 별개 설치), 로그인되어 있지 않으면 도메인 리뷰만으로 조용히 다운그레이드하지 않고 리뷰를 중단한 뒤 상황별 설정 안내(Stop Notice A: claude plugin add codex / B: codex login / C: npm install -g @openai/codex)를 출력한다. companion의 loggedIn은 CLI 가용성과 로그인의 합성값이라 .codex.available을 먼저 본다. -q --codex처럼 Quick 모드가 Codex 요청을 강제로 끄는 경우도 무음이 아니라 ⚠️ Codex 생략 고지를 낸다. 사용자가 Codex를 지목했는데 Codex 없는 결과를 받는 것이 오해를 낳는다는 판단. 런타임 실패(quota, 세션 만료 등)는 기존대로 도메인 findings만으로 계속 진행