BL-090: 정합성 linter — consistency-check 스크립트 + git pre-commit hook MVP

[bluejayA]

배경

Claude Code insight가 "self-healing layer" (PreToolUse hooks + SessionStart briefing + resumability 스킬 번들)를 추천했으나, 실제 devflow 이력 감사 결과 insight가 주장한 5가지 실패 모드 모두 증거 희박:

원안 주장	실측
wrong-branch commits	0건
stale worktrees (직접 사고)	0건
context loss on resume	0건
tool permission errors	2건 (일회성)
output token limits	0건

대신 감사에서 드러난 실제 Top Friction (빈도순):

1. 정합성 rework — N=13건 (최다)
2. 리뷰 피드백 재반영 — N=16건 (설계 품질 문제, hook 불가)
3. 게이트 UX/문구 혼동 — N=6건 (프롬프트 품질, hook 불가)

핵심 신호: 같은 이슈가 반복됨 — plugin.json hooks 필드 3회, workspace-detection 게이트 선택지 2회. 이는 체계적 체크 부재의 증거.

사용자 메모리에도 feedback_consistency_check.md, feedback_skill_impact_analysis.md로 반복 각인되어 있음.

제안 (Form A MVP)

실행 형태

• scripts/consistency-check.sh (또는 Python 단일 파일)
• .pre-commit-config.yaml 배선 → 사용자 최초 1회 pre-commit install, 이후 자동
• 수동 실행도 가능 (커밋 전 미리 확인용)

검사 범주 (감사 데이터 기반)

#	범주	사례
1	참조 그래프	aidlc:X 상호참조 stale (dispatching ↔ executing 등)
2	파일 경로	plugin.json hooks/agents/commands의 path 실재 여부
3	Frontmatter 스키마	SKILL.md 필수 필드, description 언어 규칙
4	템플릿 필드	devflow-state Worktree/PR URL 누락

명시적 제외

• auto-fix 없음 — 감지만, 수정은 사용자 판단 (CLAUDE.md "승인 없이 코드 작성 금지")
• Claude Code runtime hook 아님 — git pre-commit으로 충분, 추측된 실패 모드 방어 불필요
• LLM 호출 없음 — 정적 규칙으로 커버 가능한 1~4 범주만. 의미적 검사(용어 일관성 등)는 MVP 범위 밖
• 모든 커밋 강제 아님 — 실패 시 커밋 차단하되 --no-verify escape hatch 유지 (CLAUDE.md 원칙 존중)

원안 대비 축소 근거

원안 요소	처리
PreToolUse hooks (worktree/branch/output-size)	기각 — 실측 증거 0~2건
SessionStart briefing hook	기각 — using-devflow 스킬이 이미 A/B 재개 질문
resumability 스킬	기각 — devflow-state.md가 이미 체크포인트
"last 30 sessions" 분석	이 이슈에서 완료 (감사 리포트 참조)

선행/관련

• 선행: _shared/patterns/consistency-checklist.md 존재 — linter가 이것을 "실행 가능" 형태로 승격
• BL-089 (aidlc-cost-review)와 독립
• BL-042 (Layer 2 eval)와 별개 — linter는 정적, Layer 2는 LLM 행동 검증

범위 확장 조건 (Phase 2 재검토)

MVP 운영 후 다음 신호 관측 시 Form C(LLM 하이브리드) 검토:

• 정적 1~4로 못 잡은 rework 반복 발생
• 용어 일관성(5번 범주) friction 누적 관측
• false positive율이 실제 유용성을 상회

ROI

• 비용: 2-4시간 MVP 구현
• 편익: N=13 중 1~4 범주 약 10건 × 70% 방지 가정 = 7건 방지. 커밋 전 즉시 피드백 → 컨텍스트 스위칭 감소
• 손익분기: 몇 개월 내

우선순위

P2 — 데이터 기반 최대 friction이지만 blocking 이슈 아님

[bluejayA]

추가 항목 (2026-04-24)

BL-094(#182) 결정에 따라, 본 정합성 linter MVP 범위에 다음 항목 추가:

• session-summary.md "Traps to Avoid" 섹션 비어있음 경고: 섹션 존재하지만 (없음) 또는 빈 상태일 경우 SessionEnd hook 또는 pre-commit hook에서 경고. 사용자가 의도적으로 비웠는지 확인 유도.

이유: BL-094에서 섹션 추가 + orchestrator 회수 단계는 정의하지만 conversational gate는 reactive 강제 어려움. linter 단에서 정합성 체크로 보완.