html-finisher

name	html-finisher
version	3
description	HTML 피니싱·모바일 실측·시각화 수리 엔진. 디자인 스킬 산출 직후 1턴 완결. 트리거: HTML피니셔, html finisher, HTML최적화, HTML완성, 피니싱, 마무리, 출고, 시각화삽입, 렌더링수리, 컬러보정, 채도보정, SVG수리, 삼각측량, 적응루프, 모바일실측, 모바일깨짐, 가로넘침, 렌더킬, 수리사다리, A16, 터치타겟, safe-area, dvh, multilang, A8잡문가드, CSS구조결함, MO1. NOT: 디자인 생성(→apple-canvas·prism·editorial·box-cut·teenage), 스킬 최적화(→autoloop), AI흔적 제거만(→submission-cleanup), 카피(→copywriting-skill).
license	Proprietary. LICENSE.txt has complete terms
metadata	{"author":"jason","version":"3.0.0"}

HTML Finisher v3.0

디자인 스킬이 1차 생성한 HTML을 16축 × 5Phase × 삼각측량 × 적응적 루프로 피니싱하여 완성품을 출고한다.

v3.0 — 깨짐 방어 확장 (Breakage Defense): 세 방향으로 확장.

1. 모바일 검출 9→18항목 — A16에 가로 넘침 근본 원인 9종 추가: 고정 width>414px·플레인 거대 폰트 ≥120px(clamp 검출의 사각지대)·width:100vw·고정 그리드(≥3열) 미분기·img max-width 리셋 부재·폼 입력 iOS 포커스 줌·hover 전용 콘텐츠(터치 도달 불가)·고정 헤더 앵커 가림(scroll-margin)·keep-all 단독(긴 토큰 넘침). 전부 모바일 유효 CSS(베이스 + 모바일 media만, 데스크톱 전용 min-width 블록 제외) 기준으로 판정하고, 모바일 분기에서 같은 속성을 재정의했으면 면제 — false-positive 차단. 수리는 mobile-spec.md 수리 우선순위 사다리(근본 수리→모바일 분기→안전망→마스킹 금지)를 따른다.
2. 렌더 킬클래스 확장 — A8에 CSS 구조 결함 가드 신설: 중괄호 불균형·미닫힘 /* 주석 = 즉시 0점 + STOP + 위치 보고 (잡문 가드와 동급). 셋 다 그 지점부터 CSS 전체를 무효화하는데 정적 grep은 통과하는 부류.
3. 코드위생 확장 — A8에 중복 id·깨진 앵커·CSS 속성 오타(paddding류 — 조용히 무시되는 선언)·console.log/debugger·JS 미존재 id 참조·!important 남발(베이스 한정, 모바일 분기 면제)·meta charset·다중 h1(report/landing만) 추가. 중복 셀렉터 검사를 베이스 CSS 한정으로 수정 — @media 안 재정의(공인 오버라이드 패턴)를 중복으로 오검출하던 버그 수리.

Phase 순서를 P1→P2→P5→P3→P4로 확정 — 모바일 깨짐은 구조 결함이라 표면(컬러·형광펜) 작업 전에 수리해야 재작업이 없다.

v2.4 유지 — 잡문 가드: <style> 안 비-CSS 토큰(</content>·<mode>·<parameter>·청크 메타) 1건 = A8 즉시 0점 + STOP. CSS 파서 중단 사각지대 차단.

v2.3 유지 — 반응형 ≠ 모바일 디자인: PC 원본 + 모바일 오버라이드 분기를 하나의 디자인 패턴으로 인정. A16 선결 4축:

• MO1 — @media (max-width:480) 안에 hero/divider/h1 재정의 룰 ≥1개
• MO2 — 모바일에서 폰트 weight 변경 시 ≥700 유지 (또는 명시 안 함)
• MO3 — 모바일에서 word-break: keep-all / line-break: strict / text-wrap: balance 1개+
• MO4 — 모바일 hero(.hero-title·.divider-num·h1) 최소 폰트 ≥36px (hero 인지 유지)

MO1+MO3 동시 만족 = 오버라이드 활성 → PC clamp 폭주 false-positive 면제. 형 디자인 의도(PC 거대 hero / 모바일 별도 세팅) 보존.

v2.2 유지: P5 모바일 Phase + A16 모바일 실측축(10점). 375·390·414·768 viewport별 정적 시뮬레이션. cut 110점 만점(keynote/poster=88·report/landing=99). --mobile-strict 옵션.

Skill Boundaries

• 하는 것 — HTML 16축 점검·수정·시각화 삽입·렌더링 수리·형광펜/컬러 강제·모바일 viewport 시뮬레이션·적응적 루프·scan.py 결정적 채점+LLM 의미 채점 삼각측량·제출청소 호출
• 안 하는 것 — HTML 1차 생성(→ 디자인 스킬 5종) · 스킬 자체 최적화(→ autoloop) · AI흔적 제거만(→ submission-cleanup) · 카피(→ copywriting-skill) · 실제 모바일 디바이스 테스트(→ 외부 Playwright/BrowserStack)

When to Use

• 디자인 스킬(apple-canvas, prism, editorial, box-cut, teenage)이 HTML 1차 생성 완료한 직후
• "피니싱해줘·마무리해줘·출고해줘·최적화해줘" 요청 시
• md → HTML 변환 후 품질 점검이 필요할 때
• 모바일 점검 필요 시 — multilang 1pager·landing·키노트 모두 A16 자동 점검
• 안 쓸 때 — HTML 생성 전(디자인 스킬 먼저) · 텍스트만 정리(→ shaper-skill)

Prerequisites

#	체크	미충족 시
1	HTML 파일 존재 (1차 생성 완료)	디자인 스킬로 먼저 생성
2	원본 md 존재 (A11 변환 검증용)	md 없으면 A11 스킵, 15축 진행
3	디자인 스타일 확정	미정이면 apple 디폴트
4	프로파일 판정 (keynote/poster/report/landing)	자동 추정 — 슬라이드·풀스크린·.slide 클래스 ≥3 = keynote

⛔ 절대 규칙

#	규칙	이유
1	콘텐츠 불변 — 원문 텍스트 변경 ✗. 매 회전 텍스트 해시 비교. 불일치 = 즉시 롤백	내용 훼손 방지
2	비비드 풀채도 — S≥85%. S<70% 자동 보정 (H 유지·H 변경 ✗)	물감 탄 색 방지
3	형광펜 알약형 — 높이=글자 105%, padding합산≤0.1em, radius 0.3em	과대높이 방지
4	루프 자동 완결 — 중간 컨펌 ✗. 보고는 완료 시 1회	턴 소모 방지
5	스냅샷 롤백 — 점수 하락 or A7<10 시 직전 스냅샷으로 즉시 복원	망가짐 방지
6	제출청소 연동 — P4에서 submission-cleanup 자동 호출	AI흔적 방지
7	타임스톤 순서 — P1→P2→P5→P3→P4 인과 순서 위반 ✗	모바일 깨짐은 구조 결함 — 표면(컬러·형광펜) 전에 수리해야 재작업이 없다
8	scan.py 강제 — 매 채점은 scripts/scan.py 실행. LLM 눈대중 채점 ✗	결정적 축 정량 채점 보장
9	프로파일 분기 — keynote/poster cut=88, report/landing cut=99. 디자인 의도 위반 ✗	키노트 헤드라인 압축행간·HUD 약색을 보존
10	LLM 4축 휴리스틱 강제 — A6·A10·A12·A13 PENDING 금지. scan.py가 점수 산출	27점 누락 방지
11	프로파일 셀프-셀렉트 금지 — cut 미달 시 작업자가 프로파일 갈아 PASS 만들기 ✗. 휴리스틱 판정 고정	"통과시키려 프로파일 바꾸기" 우회로 차단
12	multilang 자동 인지 — .lang-content 또는 data-lang 2개+ 감지 시 A7 보존율 기준 완화·A11 헤딩수 차이 허용	다국어 1pager false-positive 방지
13	반응형 ≠ 모바일 디자인 — @media (max-width:480) 안에 hero 재정의 룰이 있고 줄바꿈 규칙도 있으면 PC clamp 폭주 면제	형 디자인 패턴(PC 풀 임팩트 + 모바일 별도 세팅) 인정. PC 결함 잘못 검출하여 PC hero 죽이는 압력 차단
14	잡문 가드 (v2.4) — <style> 블록 안에 비-CSS 토큰(</content>·<mode>·<parameter>·<·백틱 펜스 등) 1건이라도 발견 = A8 즉시 0점 + STOP + 위치 보고 + 형 보고	CSS 파서가 무효 토큰에서 파싱 중단 → 그 아래 모든 스타일 무효화 → 렌더링 깨짐인데 scan은 정상으로 보는 사각지대. write-chunk pollution 차단
15	CSS 구조 결함 가드 (v3.0) — 중괄호 불균형·미닫힘 주석 1건 = A8 즉시 0점 + 즉시 수리 (Phase 순서 무시)

---

16축 · 타임스톤 5Phase 정렬

축 간 인과·선후관계를 시간축으로 정렬. Phase 순서 위반 ✗.

P1 기반 — 콘텐츠 확정 (27점)

축	이름	배점	핵심
A11	md→HTML 변환검증	7	전수대조, 문법잔류, 프론트매터, 테이블. multilang은 ÷언어수 보정
A7	콘텐츠보존·정합	10	원문대조, 숫자일치, 링크유효. 킬스위치: <10 = 롤백+STOP
A6	서사흐름·리듬	10	헤드순서, PT리듬, 섹션균형, CTA위치

콘텐츠가 완전해야 나머지가 의미 있다.

P2 구조 — 시각화+레이아웃 (34점)

축	이름	배점	핵심
A12	시각화 생성·삽입	5	콘텐츠유형→시각화 매칭. 섹션당 최대 2개
A13	시각화 렌더링검증	5	SVG, flex/grid, 반응형, 깨짐수리. 수리불가→제거
A2	레이아웃·반응형	8	그리드, 브레이크포인트(≤480/768/768+), max-width, user-scalable 비차단, ≤480BP 강제
A1	줄바꿈·행분할	8	맥락·문법 줄바꿈, PC/모바일 분리, orphan, word-break
A3	타이포그래피	8	헤드 볼드, 위계, 행간 1.6~1.8, fallback, 본문≥16px

시각화 넣고 → 깨지면 수리 → 레이아웃 확정.

P5 모바일 — 실측 가드 (10점) · P2 직후 실행

축	이름	배점	핵심
A16	모바일 실측	10	viewport 375/390/414/768 정적 시뮬레이션. 기본 9항목(clamp/vw 폭주·min-width·터치타겟·wide table·100vh/dvh·safe-area·color-scheme·다국어·소형 BP) + v3.0 확장 9항목(고정 width·플레인 거대 폰트·100vw·고정 그리드·img 리셋·입력 줌·hover 전용·앵커 가림·keep-all 단독). 모바일 유효 CSS 기준·분기 재정의 면제

모바일 구조를 잡은 뒤에 표면 작업에 들어간다.

P3 표면 — 컬러+형광펜 (22점)

축	이름	배점	핵심
A15	컬러링·채도강제	5	S≥85%, HSL보정, 대비안전, 면적 15~25%
A4	컬러·가시성	7	WCAG AA 4.5:1, 링크구분, 다크모드, 교대배경
A14	형광펜	5	알약형, 대상선정, 높이105%, 컬러매핑
A5	내비게이션·인터랙션	5	햄버거 우상단, 접기 플로팅, 앵커, 터치44px

비비드 강제 → 대비 확인 → 형광펜 → 메뉴/버튼.

P4 마감 — 정리+출고 (17점)

축	이름	배점	핵심
A8	코드위생	5	중복CSS, 미사용클래스, 시맨틱태그, 빈요소
A9	접근성·인쇄	5	lang, 키보드, aria, @media print, reduced-motion
A10	AI흔적제거	7	submission-cleanup 호출, 주석·placeholder 제거

상세 점검 기준 → references/axis-checklist.md · references/mobile-spec.md

---

실행 흐름

상세 → references/loop-engine.md

① BASELINE  — `python3 scripts/scan.py input.html --md src.md --profile keynote --json` → 12축 자동채점 + LLM 4축 휴리스틱 + 스냅샷 #0
   (모바일 strict: --mobile-strict 추가 → A16 가중치 2배)

② OUTER LOOP — 5Phase 순회 P1→P2→P5→P3→P4 (최소 2바퀴, 하드캡 5바퀴)
   ※ A8 킬클래스(잡문·중괄호 불균형·미닫힘 주석) 감지 시 Phase 무시하고 즉시 수리
  │
  ├── Phase 내 축 순회
  │   ├── FAIL → 가설 → 스냅샷 → 수정
  │   ├── 재채점 (scan.py 재실행 + LLM 4축)
  │   │   ├── 점수↑ + A7≥10 → keep (스냅샷 갱신)
  │   │   ├── 점수↓ or A7<10 → discard (롤백)
  │   │   └── 부작용 → 방향 전환
  │   ├── 3회 discard → RAR
  │   └── PASS 축 → 스킵
  │
  ├── 1바퀴 완료 → 베이지안 우선순위 갱신
  │
  └── STOP 판정 (3신호 동시)
      ├── 총점 ≥ 프로파일 cut (keynote/poster=88, report/landing=99)
      ├── 16축 전부 최소 1회 점검
      └── 삼각측량 3렌즈 중 2개+ PASS

③ EXPORT — 완성본 출고 + 16축 점수 보고

스톱 조건 요약: 총점≥프로파일cut + 16축 전부 점검 + 3렌즈 2/3 PASS (동시) | 수렴(2바퀴 ≤2점) | 킬스위치(A7<10) | 하드캡 5바퀴

---

Output Path

산출물	경로
완성 HTML	mnt/outputs/{원본파일명}_finished.html
원본 백업	mnt/outputs/{원본파일명}_backup.html
모바일 진단 (옵션)	mnt/outputs/{원본파일명}_mobile_audit.md

Reference Index

파일	내용	언제
scripts/scan.py	12축 결정적 자동채점 (A1A5,A7A9,A11,A14,A15,A16)	매 채점 시
references/axis-checklist.md	16축 상세 점검 기준 정본	매 SCAN 시
references/loop-engine.md	2층 루프·삼각측량·베이지안·RAR 상세	루프 진행 시
references/highlight-spec.md	형광펜 알약형 CSS·색상·높이 규칙	A14 수정 시
references/vivid-color-spec.md	비비드 채도 강제·HSL 변환 로직	A15 수정 시
references/viz-matching.md	콘텐츠유형→시각화유형 매칭 규칙	A12 삽입 시
references/mobile-spec.md 🆕	A16 모바일 9항목 점검·수정안·viewport 표	A16 수정 시

Next Phase

• 제출 전 최종 정제 → submission-cleanup
• 배포 → github-deploy
• 세션 마무리 → session-briefing

핵심 작업 어휘

피니싱 흐름에서 다루는 작업 — HTML피니셔·HTML최적화·HTML완성·시각화 삽입·렌더링 수리·컬러 보정·알약 형광펜·채도 보정·SVG 수리·적응 루프·모바일 실측. P1 트리거가 hit하면 본 스킬이 발동된다.

Failure Modes (Gotchas)

함정	대응
특정 축만 집중	외부 루프 5Phase 전축 순회. 최소 2바퀴
수정→품질 하락	스냅샷+롤백. 점수↓=discard
시각화 무한루프	A12→A13 즉시 검증. 수리불가→제거
형광펜 높이 과대	padding 합산 > 0.1em = FAIL. 알약형 강제
파스텔 보정 시 H 변경	H 고정 + S만 85%로. H 변경 ✗
콘텐츠 실수 변경	매 회전 텍스트 해시 비교. 불일치 = 즉시 롤백
90점 1바퀴 달성	최소 2바퀴 강제
규칙PASS+읽기어려움	독자렌즈가 잡음. 2렌즈+ PASS
축간 부작용	베이지안 영향 매트릭스. 파급력순 수정
3회 discard	RAR 3갈래 탈출구
submission-cleanup 미연결	A10 수동 점검 폴백
원본 md 없음	A11 스킵, 15축 진행
디자인 스타일 미확정	apple 디폴트. 형광펜=#FFE600
scan.py 미실행·눈대중 채점	절대규칙 8 위반. 결정적 축은 반드시 스크립트 실행
scan.py FAIL+LLM PASS	scan.py 우선. 결정적 축=스크립트 정답
프로파일 미지정 시 false-positive	report 디폴트라 키노트는 항상 --profile keynote 명시
var(--lime) 같은 CSS 변수 색이 미검출	v2.1에서 :root 변수 추출·치환 자동 처리
BG=BG 동색(1.0:1) FAIL	풀블리드 슬라이드 변경 컨텍스트 — v2.1에서 자동 skip
.dim·.hint·.kicker 같은 의도된 약색 FAIL	sub-noise 화이트리스트가 자동 면제
cut 못 넘으면 프로파일 갈아 PASS	절대규칙 11 — 프로파일 한 번 정하면 변경 ✗
multilang 1pager A7·A11 false-positive	절대규칙 12 — .lang-content 감지 시 자동 보정
clamp 모바일 폭주 못 잡음	A16이 vw 환산하여 자동 검출
터치타겟 grep 미달	A16이 height<44 + 형제 min-height 부재 패턴 검출
fixed 점유율 false-positive	visibility:hidden·display:none 닫힘 상태는 점수 차감 ✗. A16은 정적이라 컴포넌트별 점검은 P5 휴리스틱으로
wide table 가로넘침	A16이 8열+ tr 감지 → overflow-x:auto 부모 확인
안 잡문 (v2.4) — </content>·<mode>·<parameter>·antml: 등 write-chunk pollution	A8이 즉시 0점·STOP. 발견 위치 보고 후 형이 청크 메타 제거. CSS 파서 파싱 중단 사각지대 차단

❌ WRONG vs ✅ CORRECT

❌ WRONG: A1→A16 기계적 선형 순서로 전축 동시 수정
✅ CORRECT: 타임스톤 5Phase 인과 순서 + Phase 내 가설 기반 1~2축 집중 수정

❌ WRONG: 85점 1바퀴 도달 → 즉시 출고 / cut 못 넘어 프로파일 갈아 PASS
✅ CORRECT: 최소 2바퀴 + 프로파일 컷 + 16축 전부 점검 + 3렌즈 2개+ PASS (3신호 동시) + 프로파일 고정

❌ WRONG: 모바일 점검 없이 88점 PASS → 출고
✅ CORRECT: A16 점검 강제. clamp 폭주·터치<44·wide table·100vh·safe-area·multilang 비대칭 9항목 통과

❌ WRONG: 한 단어로 "반응형 OK" 처리
✅ CORRECT: scan.py가 375/390/414/768 각 viewport에서 clamp 환산·min-width 검사 결정적 채점

❌ WRONG: PC clamp(280px, 30vw, 292px) → "모바일에서 280px 폭주" FAIL → PC hero 줄여라
✅ CORRECT: @media (max-width:480) 안에 hero 재정의 + keep-all 있으면 오버라이드 활성 → PC clamp 의도 발현 인정 → MO4(모바일 hero ≥36px·볼드 유지)만 검사

❌ WRONG: "반응형 단일 디자인이 정답"
✅ CORRECT: PC 풀 임팩트 + 모바일 별도 세팅이 정상 패턴. MO1~MO4 분기 품질만 검증

❌ WRONG (v2.4): <style> 안에 </content>·<mode>rewrite</mode>·<parameter> 잔여 → scan PASS인데 브라우저는 그 지점부터 CSS 파싱 중단 → topbar 안 보임
✅ CORRECT (v2.4): A8 잡문 가드가 즉시 0점 + 위치 보고 + STOP → 형이 잡문 제거 후 재실행

❌ WRONG (v3.0): 모바일에서 .wide-box가 화면을 뚫음 → body { overflow-x: hidden }으로 덮고 PASS 처리
✅ CORRECT (v3.0): 수리 사다리 — ① .wide-box에 max-width:100% ② 안 되면 @media 분기 재정의 ③ 표 같은 건 부모 overflow-x:auto. 마스킹은 금지

❌ WRONG (v3.0): A16 FAIL을 고치겠다고 컬러·형광펜(P3) 끝낸 HTML의 레이아웃을 다시 뜯음
✅ CORRECT (v3.0): P5는 P2 직후 — 모바일 구조를 확정한 뒤에 표면 작업 진입