docs(S15P11A705-292): 프리셋 표시 라벨·축 정의 개정안 P47 신설

[colosair]

요약

외부 리뷰 문서를 P47 제안 문서로 다시 써서 docs/proposals/ 에 넣는다. 프리셋의 표시 라벨·축 정의·스키마 개정안이다.

§6(표시 라벨)은 이미 반영됐고, 나머지는 제안으로 남는다. 표시명 명사화는 같은 티켓이 #102(dev)·#104(main)로 이미 내보냈다. 이 PR 은 그 결과를 문서에 반영하고, 아직 실행되지 않은 나머지(§7 이후)를 제안 상태로 남긴다.

문서 변경만 있다. 코드·데이터·계약 파일을 건드리지 않는다 — data/keyword_preset.yaml 은 #102 에서 이미 병합됐고 이 PR 은 그 파일을 열지 않는다.

Jira (필수)

• 키 또는 URL: S15P11A705-292 — https://ssafy.atlassian.net/browse/S15P11A705-292
• 완료 조건: 표시명 명사화 개정의 근거 문서가 레포에 남고, 그 문서가 실제 반영값과 일치한다. 반영 자체는 #102·#104 에서 끝났다.

새 티켓을 발행하지 않았다. P47 §6 이 -292 작업의 근거이고 이 문서가 그 결과를 담으므로 같은 티켓에 묶는다. 조회 시점의 상태는 진행 중 이었다.

변경 사항

파일	무엇을·왜
docs/proposals/P47-keyword-preset-label-axis.md (신설)	제안 본문. 축 재정의 · 표시 라벨 · examples · 스키마 · loader/DB · 평가 · 적용 순서
docs/proposals/README.md	「개별 문서」 표에 P47 행 추가(Proposed). tools/check_docs_index.py 는 proposals 를 검사하지 않으므로 손으로 맞췄다 — 기존 행과 컬럼 형식을 대조했다
docs/WORKLOG.md	시간축 한 줄. merge=union 대상이라 추가만 한다

문서 안에서 오늘 확정·실행된 것에 맞춰 고친 지점은 다음과 같다.

• 머리말 — 관련 PR 에 #102·#104, 관련 티켓에 -292 추가. 「§6 은 반영 완료」를 머리말에서 밝힌다.
• §6 — 절 제목을 「반영 완료」로 바꾸고 티켓·PR 을 가리킨다. 표의 「권장 표시명」을 실제 반영값으로 맞추고 컬럼을 「개정 전 → 반영값」으로 고쳤다. §6.4 는 셋이 다 확정됐으므로 확정 기록으로 정리했다.
• §4 — 선결 조건을 「판을 구분할 경로」에서 **「재처리할 수단」**으로 교체.
• §3-F — 행 version 을 올릴 경로가 없다는 사실을 여기로 옮기고, 우선순위를 낮춘 근거를 붙였다.
• §12.1 — 「재처리를 하는가」를 **「전부 재처리한다」**로 확정. 남는 질문은 「어떻게」다.
• §10.3 — 세트 release 의 운영 용도가 빠져 우선순위가 내려간 것을 절 제목과 본문에 명시.
• §11.4 — 비교군 N 이 이미 반영됐으므로 실측 기준선이 BASE 가 아니라 N 임을 덧붙였다.
• §13 — 0단계에서 판 구분·재처리 방침이 빠지고 재처리 수단 구현·저빈도 프리셋 처분 둘이 남는다. 1단계는 표시명 명사화가 끝났으므로 examples 정비와 그 측정만 남는다.
• §14 — 「이 문서는 Accepted 가 아니다」는 유지하되, §6 이 실측 없이 먼저 나갔다는 사실을 감수 항목으로 새로 넣었다.

설계 결정

1. 왜 Proposed 인가

§6 만 실행됐고 §7(examples) 이후가 전부 미실행이며 §11 의 실측이 없다. 부분 반영으로 문서 상태를 올리면 나머지 절이 확정된 결정처럼 읽힌다 — proposals/README.md 가 「Accepted 인 것은 확정된 결정이며 구현이 따라야 한다」로 규정하므로 그 오독의 대가가 크다.

대신 반영된 절만 문서 안에서 격상했다. 상태 필드는 문서 단위이고 반영 여부는 절 단위라 층이 다르다.

2. 왜 값을 안 적었는가

§0 이 이 문서의 규칙이다 — 측정 수치·현행 상수·코드 행 번호·배포 상태 값을 넣지 않고 어디에 있는지만 가리킨다. 값은 시점에 묶이는데 문서는 따라가지 않고, 낡은 값이 다음 결정의 근거가 된다(이 프로젝트에서 세 번 났다).

이번 수정에도 같은 규칙을 적용했다. 새로 쓴 문장에 수치·행 번호가 없다. 티켓·PR·이슈 번호는 좌표라 넣었다.

예외는 §6.2 의 표 하나다. 표시명 자체가 결정 내용이라 안 적을 수 없다. 그래서 표 앞에 정본은 data/keyword_preset.yaml 이고 표와 어긋나면 YAML 이 옳다고 못박았다.

3. ALONE·TRENDY·RETRO 를 어떻게 정했는가

code	초안	확정	근거
ALONE	1인 권장	혼자 유지	데이터 규칙(엄격한 명사형)보다 UI 자연스러움을 앞세웠다. 축의 나머지가 관계를 가리키는데 수량 표현만 어휘 층위가 다르다
TRENDY	감성 으로 두되 판단 유보	감성	code 는 유행을 가리키지만 examples 가 실제로 가리키는 것은 사진·인테리어의 미감이다. 표시가 실제 의미를 따른다
RETRO	유지	복고	초안에 없던 결정이다. 같은 축의 나머지가 전부 추상명사인데 이것만 외래어라 어휘 층위가 섞이고, description 이 이미 「복고」를 쓴다

TRENDY 는 표시만 정했고 code 와 뜻의 간극은 남는다 — §14 가 감수 항목으로 안는다.

4. 선결 조건을 왜 갈아치웠는가

원래 선결 조건은 「개정 전후 판정을 DB 에서 구분할 경로」였다. 「전부 재처리한다」가 정해지면서 그 용도가 사라졌다 — 골라낼 일이 없으면 판을 구분할 이유가 준다.

대신 재처리할 수단이 없다는 것이 선결 조건이 된다. 완료 State 를 되돌리는 코드가 없고, 재스캔이 잡는 상태에 완료가 없으며, 한 번에 밀면 게이트웨이 한도에 걸려 재시도 예산이 소진되면 실패로 굳는다. 부재의 범위는 #100 이 다룬다. 「정할 것」에서 「만들 것」으로 성격이 바뀌었다.

테스트 / 검증

문서 전용 변경이라 런타임 영향이 없다. 애플리케이션 코드·데이터·스키마를 건드리지 않으므로 RED/GREEN 이 적용되지 않는다. 대신 문서가 지킬 수 있는 것을 검사했다.

RED

• 적용 불가. 동작 변경이 없다.
• 대신 문서와 실제의 불일치를 먼저 관측했다 — 초안의 §6.2 는 ALONE 을 1인, RETRO 를 레트로 로 적고 있었고 TRENDY 는 판단을 유보한 상태였다. 셋 다 실제 반영값과 달랐다.

GREEN

• 27개 전량 대조 — git show origin/main:data/keyword_preset.yaml 에서 뽑은 display_name 과 §6.2 표를 프로그램으로 짝지어 비교했다. 27/27 일치.
• 미확정 표기 전수 검사 — 「재론」·「미확정」·「정하지 않는다」가 §6 관련 절에 남아 있지 않다.
• 인코딩 전수 검사 — 세 파일에서 U+FFFD 0건, 한글 자모 분리 0건.
• 헤딩 검사 — 새로 쓰거나 고친 제목·소제목에 서술식 어미가 없다.

Regression

• ruff check . — All checks passed
• python -m compileall app tools — exit 0
• pytest --cov=app --cov-branch --cov-report=term-missing — 실행하지 않았다. 이 PR 은 app/·tests/ 를 건드리지 않아 커버리지 분모·분자가 움직이지 않는다. CI 의 ai-ci / check 가 전량 돌리며, 실패하면 병합 전에 고친다.
• python tools/check_docs_index.py — 문서 색인 정합 통과
• DB 계약 변경 시 pgvector Testcontainers 검증 — 해당 없음(스키마 무변경)

CI 가 검사하는 것 — PR 제목 형식({type}(S15P11A705-N): ), base 브랜치 규칙, Ruff, compile, pytest/Testcontainers, coverage 게이트, 컨테이너 빌드. 이 PR 이 실질적으로 거는 것은 앞의 셋이다.

tools/check_docs_index.py 는 proposals 를 검사하지 않는다. 그쪽 전수 표는 M## 처럼 개별 문서가 없는 행을 담고 상태 전이가 파일의 용도 자체라 자동 검사의 대상이 아니다(.gitattributes 주석에 근거가 있다). 따라서 P47 색인 행은 사람이 맞췄고, 기존 행과 컬럼 형식을 대조했다.

리뷰 포인트

1. §6 이 「반영 완료」로 읽히는가. 절 제목·서두·표 컬럼(「개정 전 → 반영값」) 셋이 같은 방향을 가리켜야 한다. 다음 사람이 이 절을 다시 제안으로 읽으면 실패다.
2. 미확정 표기가 남지 않았는가. §6.4 는 셋 다 확정 기록으로 바꿨다. 「재론」·「미확정」류 표현이 하나라도 남으면 안 된다.
3. §6.2 의 27개가 실제 display_name 과 같은가. 프로그램으로 대조했으나 눈으로도 봐 주면 좋다. 틀렸을 때의 정본은 YAML 이며 그 사실이 표 앞에 적혀 있다.
4. 선결 조건 교체가 과한 판단이 아닌가. 「전부 재처리」가 「판 구분」을 필요 없게 만든다는 논리에 구멍이 있으면 §4·§12.1·§13 0단계가 함께 틀린다. 판 구분을 완전히 버리지 않고 §3-F 에 우선순위를 낮춰 남긴 것이 이 리스크의 대비다.
5. §14 의 자기 고백이 충분한가. §6 이 §11 실측 없이 먼저 나간 것은 이 문서의 원래 주장(「실측 없이 반영하면 되짚을 수 없다」)과 충돌한다. 무르지 않고 감수 항목으로 적었으나, 표현이 약하면 강화가 필요하다.

리스크

• 계약: 없음. 공용 계약(docs 레포)·spec/ 을 건드리지 않는다. §12.4 가 스키마 개정 시 따라올 공용 계약 개정 단계를 예고할 뿐이다.
• 데이터·개인정보: 없음. 실사용자 기록·상호명·개인 식별 정보가 문서에 없다. visibility 정책은 이 PR 의 범위 밖이며 §6.1 이 「바꾸지 않는다」로 고정한다.
• 운영·배포: 없음. 이미지 publish 는 main push 에서만 일어나고 이 PR 의 base 는 dev 다. 프리셋 봉인 값은 #102 에서 이미 갱신 요청됐다.
• 문서 리스크: §6.2 표가 YAML 과 갈라질 수 있다. 자동 검사가 없어 사람이 맞춰야 한다 — 그래서 정본이 YAML 이라는 사실을 표 앞에 명시했다.

범위 밖 / 후속

이번 PR 에서 다루지 않는 항목:

• 재처리 수단 구현 — §4·§13 0단계. 완료 State 회수 경로·재스캔 대상·속도 조절과 예산 규칙. #100 이 부재를 다루고 있다.
• 저빈도 프리셋 처분 — §12.2·§13 0단계. 유지·병합·폐기 판단이 라벨 개정보다 앞선다.
• examples 정비와 그 측정 — §7·§11·§13 1단계. 축 오염 제거와 전체 재임베딩·반복 회차 측정.
• 행 version 개정 경로 — §3-F. S15P11A705-269 가 추적한다.
• display_name 실측 재평가 — §6 반영이 판정에 얼마나 파급됐는지는 재지 않았다. §11 에 남는다.
• data/keyword_preset.yaml 수정 — #102 에서 병합됐고 이 PR 은 열지 않는다.

후속 Jira: S15P11A705-269(preset_version 경로) · S15P11A705-270(DE 부호) · S15P11A705-271(description 층 분리). 재처리 수단과 저빈도 프리셋 처분은 아직 티켓이 없다.

영구 문서

• docs/proposals/P47-keyword-preset-label-axis.md — 신설
• docs/proposals/README.md — 색인 한 줄
• docs/WORKLOG.md — 시간축 한 줄

관련 GitHub Issue (선택)

• #100 — FAILED 회수 경로 부재. §4 의 재처리 수단 부재와 같은 구멍의 다른 면이다.