341 lines
20 KiB
Python
341 lines
20 KiB
Python
#!/usr/bin/env python3
|
||
"""design-direction 아티팩트 린터(정본).
|
||
|
||
파일/hash 무결성뿐 아니라 발산 전 조형영역 분할과 선택 전 비교 감사를 강제한다.
|
||
시각적 취향을 숫자로 위장하지는 않되, 같은 카드 셸의 색상 변주처럼 계약으로
|
||
판별 가능한 수렴은 decision 단계에 들어가기 전에 fail closed 한다.
|
||
"""
|
||
import os, sys, yaml, hashlib, itertools, re
|
||
|
||
ROOT = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
|
||
_IB_REQUIRED = ["product-goal", "core-users", "core-tasks", "information-density",
|
||
"required-accessibility", "brand-constraints", "avoid-cliches",
|
||
"representative-screen-requirement", "tech-platform-constraints"]
|
||
_IB_PROHIBITED = ["reference-cluster", "color-palette", "typography", "layout-grammar", "tokens", "visual-metaphor"]
|
||
_DIR_REQUIRED = ["id", "producer-role-id", "producer-run-id", "context-package-id", "concept-artifact",
|
||
"reference-cluster", "visual-thesis", "layout-grammar", "interaction-grammar",
|
||
"typography-token-direction", "primitive-inventory",
|
||
"reference-board-ref", "reference-board-sha256",
|
||
"full-size-preview-ref", "full-size-preview-sha256",
|
||
"coded-slice", "coded-slice-sha256"]
|
||
_CHARTER_AXES = ["layout-topology", "navigation-model", "typography-voice",
|
||
"imagery-strategy", "motion-model", "dominant-primitives"]
|
||
_CHARTER_REQUIRED = ["id", "design-question", *_CHARTER_AXES,
|
||
"exclusive-primitives", "forbidden-primitives"]
|
||
_GENERIC = ["modern", "clean", "minimal", "sleek"]
|
||
_VAGUE = ["분위기", "감성", "스타일", "느낌", "mood", "vibe", "aesthetic"]
|
||
_BRIEF_PRODUCT_ANCHORS = re.compile(r"\b(duolingo|brilliant|linear|notion|stripe|figma)\b", re.I)
|
||
_BRIEF_DIRECTION_EXAMPLES = re.compile(
|
||
r"(?:예\s*[:：]|e\.g\.|for example|가이드\s*트레일|guided[- ]?trail|playful[- ]?probe|"
|
||
r"놀이형\s*탐구|이야기\s*챕터|story\s*chapter)", re.I)
|
||
|
||
def _load(path):
|
||
try:
|
||
doc = yaml.safe_load(open(path)) or {}
|
||
if isinstance(doc, dict) and doc.get("report-type") == "workflow-artifact":
|
||
return doc.get("payload") if isinstance(doc.get("payload"), dict) else {}
|
||
return doc
|
||
except Exception as e: return {"__err__": str(e)}
|
||
def _abs(p): return p if os.path.isabs(p) else os.path.join(ROOT, p)
|
||
def _file_sha(p):
|
||
ap = _abs(p)
|
||
return hashlib.sha256(open(ap, "rb").read()).hexdigest() if os.path.isfile(ap) else None
|
||
|
||
def _norm(value):
|
||
return re.sub(r"[^a-z0-9가-힣]+", "-", str(value or "").strip().lower()).strip("-")
|
||
|
||
def _items(value):
|
||
if isinstance(value, list):
|
||
return {_norm(v) for v in value if _norm(v)}
|
||
if isinstance(value, str):
|
||
return {_norm(value)} if _norm(value) else set()
|
||
return set()
|
||
|
||
def _pairs(ids):
|
||
return {tuple(sorted(pair)) for pair in itertools.combinations(ids, 2)}
|
||
|
||
def _pair_id(value):
|
||
if isinstance(value, (list, tuple)) and len(value) == 2:
|
||
return tuple(sorted(str(x) for x in value))
|
||
return None
|
||
|
||
def _hash_bound_file(ref, sha, label):
|
||
if not ref or not sha:
|
||
return f"{label}: ref+sha256 필요"
|
||
live = _file_sha(ref)
|
||
if live is None:
|
||
return f"{label}: 파일 없음({ref})"
|
||
if live != sha:
|
||
return f"{label}: sha256 불일치"
|
||
return None
|
||
|
||
def lint_file(path, kind):
|
||
doc = _load(path)
|
||
if "__err__" in doc: return ([f"{kind}: YAML 파싱 실패 — {doc['__err__']}"], [])
|
||
if not isinstance(doc, dict): return ([f"{kind}: 최상위가 매핑 아님"], [])
|
||
return {"direction-input-brief": _lint_input_brief,
|
||
"divergence-charter": _lint_divergence_charter,
|
||
"direction-set": _lint_direction_set,
|
||
"comparative-divergence-audit": _lint_comparative_audit,
|
||
"direction-discovery": _lint_discovery, "winner-prototype": _lint_winner}.get(
|
||
kind, lambda d: ([f"unknown kind: {kind}"], []))(doc)
|
||
|
||
def _lint_input_brief(doc):
|
||
hard = [f"direction-input-brief: 필수 '{k}' 없음" for k in _IB_REQUIRED if not doc.get(k)]
|
||
hard += [f"direction-input-brief: '{k}' 포함 금지(발산 전 고착 S1)" for k in _IB_PROHIBITED if doc.get(k)]
|
||
# Problem/experience invariants belong here; competitor products and named
|
||
# solution directions belong in the post-brief divergence-charter. Without
|
||
# this boundary all isolated workers receive the same latent UI template.
|
||
brand = str(doc.get("brand-constraints") or "")
|
||
representative = doc.get("representative-screen-requirement") or {}
|
||
rep_text = (str(representative.get("description") or "")
|
||
if isinstance(representative, dict) else str(representative))
|
||
if _BRIEF_PRODUCT_ANCHORS.search(brand):
|
||
hard.append("direction-input-brief: brand-constraints에 경쟁제품 UI anchor 금지 — brand truth만 두고 reference는 divergence 이후 정의")
|
||
if _BRIEF_DIRECTION_EXAMPLES.search(rep_text):
|
||
hard.append("direction-input-brief: representative-screen에 방향/메타포 예시 금지 — 동일 의미적 task/state만 명시")
|
||
return (hard, [])
|
||
|
||
def _lint_direction_set(doc):
|
||
hard, warn = [], []
|
||
dirs = doc.get("directions") or []
|
||
if len(dirs) < 3: hard.append(f"direction-set: 방향 >= 3 필요(현재 {len(dirs)})")
|
||
if not doc.get("direction-cycle-id"): hard.append("direction-set: direction-cycle-id 필요")
|
||
for k in ("divergence-charter-ref", "divergence-charter-sha256"):
|
||
if not doc.get(k): hard.append(f"direction-set: {k} 필요")
|
||
rs = doc.get("representative-screen") or {}
|
||
if not (rs.get("id") and rs.get("kind")): hard.append("direction-set: representative-screen(id/kind) 필요")
|
||
cp = doc.get("comparison-preview") or {}
|
||
for k in ["receipt-ref", "receipt-sha256", "gallery-path", "representative-screen-id"]:
|
||
if not cp.get(k): hard.append(f"direction-set: comparison-preview.{k} 필요(실제 비교 렌더 증거)")
|
||
if cp.get("representative-screen-id") and rs.get("id") and cp["representative-screen-id"] != rs["id"]:
|
||
hard.append("direction-set: comparison-preview 가 대표화면과 불일치")
|
||
for d in dirs:
|
||
if not isinstance(d, dict): hard.append("direction-set: direction 이 매핑 아님"); continue
|
||
miss = [k for k in _DIR_REQUIRED if not d.get(k)]
|
||
if miss: hard.append(f"direction-set: {d.get('id','?')} 필수 누락 {miss}")
|
||
cs, csha = d.get("coded-slice"), d.get("coded-slice-sha256")
|
||
if cs and csha and _file_sha(cs) not in (None, csha):
|
||
hard.append(f"direction-set: {d.get('id','?')} coded-slice hash 불일치")
|
||
elif cs and _file_sha(cs) is None:
|
||
hard.append(f"direction-set: {d.get('id','?')} coded-slice 파일 없음(실제 픽셀 필요)")
|
||
for ref_key, sha_key in (("reference-board-ref", "reference-board-sha256"),
|
||
("full-size-preview-ref", "full-size-preview-sha256")):
|
||
err = _hash_bound_file(d.get(ref_key), d.get(sha_key),
|
||
f"direction-set: {d.get('id','?')} {ref_key}")
|
||
if err: hard.append(err)
|
||
refs = d.get("reference-cluster") or []
|
||
if not (isinstance(refs, list) and 3 <= len(refs) <= 6):
|
||
hard.append(f"direction-set: {d.get('id','?')} reference-cluster 3~6개 필요")
|
||
for ref in refs:
|
||
if not isinstance(ref, dict) or any(not ref.get(k) for k in ("name", "signal", "why-relevant")):
|
||
hard.append(f"direction-set: {d.get('id','?')} reference 는 name/signal/why-relevant 필수")
|
||
continue
|
||
if any(g in (str(ref.get("name","")) + str(ref.get("signal",""))).lower() for g in _GENERIC):
|
||
warn.append(f"direction-set: {d.get('id','?')} reference 형용사(generic-risk)")
|
||
# 같은 레퍼런스 집합은 독립 실행이어도 같은 latent default 로 수렴시킨다.
|
||
for left, right in itertools.combinations([d for d in dirs if isinstance(d, dict)], 2):
|
||
lrefs = {_norm(r.get("name")) for r in (left.get("reference-cluster") or []) if isinstance(r, dict)}
|
||
rrefs = {_norm(r.get("name")) for r in (right.get("reference-cluster") or []) if isinstance(r, dict)}
|
||
overlap = sorted((lrefs & rrefs) - {""})
|
||
if len(overlap) > 1:
|
||
hard.append(f"direction-set: {left.get('id')}↔{right.get('id')} reference 중복 >1 ({overlap})")
|
||
return (hard, warn)
|
||
|
||
def _lint_divergence_charter(doc):
|
||
hard, warn = [], []
|
||
dirs = doc.get("directions") or []
|
||
if len(dirs) != 3:
|
||
hard.append(f"divergence-charter: 정확히 3개 방향 필요(현재 {len(dirs)})")
|
||
if not doc.get("direction-cycle-id"):
|
||
hard.append("divergence-charter: direction-cycle-id 필요")
|
||
rs = doc.get("representative-screen") or {}
|
||
if not (isinstance(rs, dict) and rs.get("id") and rs.get("kind") and rs.get("description")):
|
||
hard.append("divergence-charter: representative-screen id/kind/description 필요")
|
||
ids = [str(d.get("id")) for d in dirs if isinstance(d, dict) and d.get("id")]
|
||
if len(set(ids)) != len(ids):
|
||
hard.append("divergence-charter: direction id 중복")
|
||
for d in dirs:
|
||
if not isinstance(d, dict):
|
||
hard.append("divergence-charter: direction 이 매핑 아님")
|
||
continue
|
||
miss = [k for k in _CHARTER_REQUIRED if not d.get(k)]
|
||
if miss:
|
||
hard.append(f"divergence-charter: {d.get('id','?')} 필수 누락 {miss}")
|
||
if len(_items(d.get("dominant-primitives"))) < 2:
|
||
hard.append(f"divergence-charter: {d.get('id','?')} dominant-primitives >=2")
|
||
if len(_items(d.get("exclusive-primitives"))) < 2:
|
||
hard.append(f"divergence-charter: {d.get('id','?')} exclusive-primitives >=2")
|
||
if len(_items(d.get("forbidden-primitives"))) < 2:
|
||
hard.append(f"divergence-charter: {d.get('id','?')} forbidden-primitives >=2")
|
||
for left, right in itertools.combinations([d for d in dirs if isinstance(d, dict)], 2):
|
||
differing = [axis for axis in _CHARTER_AXES if _norm(left.get(axis)) != _norm(right.get(axis))]
|
||
if len(differing) < 4:
|
||
hard.append(f"divergence-charter: {left.get('id')}↔{right.get('id')} 조형축 차이 <4 ({differing})")
|
||
overlap = _items(left.get("exclusive-primitives")) & _items(right.get("exclusive-primitives"))
|
||
if overlap:
|
||
hard.append(f"divergence-charter: {left.get('id')}↔{right.get('id')} exclusive primitive 충돌 {sorted(overlap)}")
|
||
expected = _pairs(ids)
|
||
entries = doc.get("pairwise-separation") or []
|
||
actual = {_pair_id(e.get("directions")) for e in entries if isinstance(e, dict)} - {None}
|
||
if expected != actual:
|
||
hard.append(f"divergence-charter: pairwise-separation coverage 불일치(expected={sorted(expected)}, actual={sorted(actual)})")
|
||
for e in entries:
|
||
if not isinstance(e, dict):
|
||
continue
|
||
axes = set(e.get("differing-axes") or [])
|
||
if len(axes & set(_CHARTER_AXES)) < 4:
|
||
hard.append(f"divergence-charter: pair {e.get('directions')} differing-axes >=4")
|
||
if e.get("allowed-overlap") in (None, ""):
|
||
hard.append(f"divergence-charter: pair {e.get('directions')} allowed-overlap 명시 필요")
|
||
return hard, warn
|
||
|
||
def _lint_comparative_audit(doc):
|
||
hard, warn = [], []
|
||
for k in ("direction-cycle-id", "divergence-charter-ref", "divergence-charter-sha256",
|
||
"direction-set-ref", "direction-set-sha256", "reviewer-role-id", "reviewer-run-id",
|
||
"verdict", "pairwise-comparisons", "full-size-previews"):
|
||
if doc.get(k) in (None, "", []):
|
||
hard.append(f"comparative-divergence-audit: {k} 필요")
|
||
if doc.get("verdict") not in ("pass", "revise", "re-diverge"):
|
||
hard.append("comparative-divergence-audit: verdict=pass|revise|re-diverge")
|
||
if not isinstance(doc.get("blocking-findings"), list):
|
||
hard.append("comparative-divergence-audit: blocking-findings 목록 필요(없으면 [])")
|
||
if doc.get("verdict") == "pass" and doc.get("blocking-findings"):
|
||
hard.append("comparative-divergence-audit: blocking finding 존재 시 pass 금지")
|
||
return hard, warn
|
||
|
||
def lint_divergence_bundle(audit_path, direction_set_path, charter_path):
|
||
"""charter→direction-set→comparative audit의 exact hash/cycle/pair coverage 검증."""
|
||
charter, ds, audit = _load(charter_path), _load(direction_set_path), _load(audit_path)
|
||
hard, warn = [], []
|
||
for doc, name in ((charter, "divergence-charter"), (ds, "direction-set"),
|
||
(audit, "comparative-divergence-audit")):
|
||
if "__err__" in doc or not isinstance(doc, dict):
|
||
hard.append(f"{name}: bundle 로드 실패")
|
||
if hard:
|
||
return hard, warn
|
||
for fn, doc in ((_lint_divergence_charter, charter), (_lint_direction_set, ds),
|
||
(_lint_comparative_audit, audit)):
|
||
h, w = fn(doc); hard.extend(h); warn.extend(w)
|
||
csha, dsha = _file_sha(charter_path), _file_sha(direction_set_path)
|
||
if ds.get("divergence-charter-sha256") != csha:
|
||
hard.append("divergence bundle: direction-set charter hash 불일치")
|
||
if audit.get("divergence-charter-sha256") != csha:
|
||
hard.append("divergence bundle: audit charter hash 불일치")
|
||
if audit.get("direction-set-sha256") != dsha:
|
||
hard.append("divergence bundle: audit direction-set hash 불일치")
|
||
cycles = {charter.get("direction-cycle-id"), ds.get("direction-cycle-id"), audit.get("direction-cycle-id")}
|
||
if len(cycles) != 1:
|
||
hard.append(f"divergence bundle: cycle-id 불일치 {sorted(str(x) for x in cycles)}")
|
||
ids = [str(d.get("id")) for d in (ds.get("directions") or []) if isinstance(d, dict) and d.get("id")]
|
||
expected = _pairs(ids)
|
||
comparisons = audit.get("pairwise-comparisons") or []
|
||
actual = {_pair_id(e.get("directions")) for e in comparisons if isinstance(e, dict)} - {None}
|
||
if expected != actual:
|
||
hard.append("divergence bundle: pairwise-comparisons coverage 불일치")
|
||
for e in comparisons:
|
||
if not isinstance(e, dict):
|
||
continue
|
||
if len(set(e.get("differing-axes") or []) & set(_CHARTER_AXES)) < 4:
|
||
hard.append(f"divergence bundle: pair {e.get('directions')} differing-axes <4")
|
||
if e.get("primitive-collisions"):
|
||
hard.append(f"divergence bundle: pair {e.get('directions')} primitive collision 존재")
|
||
previews = audit.get("full-size-previews") or []
|
||
preview_ids = {str(p.get("direction-id")) for p in previews if isinstance(p, dict)}
|
||
if set(ids) != preview_ids:
|
||
hard.append("divergence bundle: full-size-previews 방향 coverage 불일치")
|
||
for p in previews:
|
||
if not isinstance(p, dict):
|
||
continue
|
||
err = _hash_bound_file(p.get("ref"), p.get("sha256"),
|
||
f"divergence bundle: {p.get('direction-id')} preview")
|
||
if err: hard.append(err)
|
||
if audit.get("verdict") != "pass":
|
||
hard.append(f"divergence bundle: comparative audit pass 필요(현재 {audit.get('verdict')})")
|
||
if audit.get("blocking-findings"):
|
||
hard.append("divergence bundle: blocking findings 존재")
|
||
return hard, warn
|
||
|
||
def _lint_discovery(doc):
|
||
hard = [f"direction-discovery: 필수 '{k}' 없음" for k in
|
||
["direction-input-brief-sha256", "findings", "constraints-restated"] if not doc.get(k)]
|
||
return (hard, [])
|
||
|
||
def _lint_winner(doc):
|
||
hard = [f"winner-prototype: 필수 '{k}' 없음" for k in
|
||
["selected-direction-ref", "selected-direction-sha256", "prototype-path", "prototype-sha256",
|
||
"preview-receipt-ref", "revision"] if not doc.get(k)]
|
||
if doc.get("prototype-path"):
|
||
if _file_sha(doc["prototype-path"]) is None:
|
||
hard.append("winner-prototype: prototype 파일 없음")
|
||
elif doc.get("prototype-sha256") and _file_sha(doc["prototype-path"]) != doc["prototype-sha256"]:
|
||
hard.append("winner-prototype: prototype hash 불일치")
|
||
return (hard, [])
|
||
|
||
def lint_selected_direction(selected_path, direction_set_path):
|
||
"""selected+direction-set BUNDLE 검증(Blocker 8)."""
|
||
sd, ds = _load(selected_path), _load(direction_set_path)
|
||
if "__err__" in sd or not isinstance(sd, dict): return ([f"selected-direction: 로드 실패"], [])
|
||
if "__err__" in ds or not isinstance(ds, dict): return ([f"selected-direction: direction-set 로드 실패"], [])
|
||
hard, warn = [], []
|
||
for k in ["direction-set-ref", "direction-set-sha256", "parent-workflow-id",
|
||
"product-decision-id", "direction-input-brief-sha256", "selection-acceptance-receipt"]:
|
||
if not sd.get(k): hard.append(f"selected-direction: 필수 '{k}' 없음")
|
||
if "secondary-influence-id" in sd: hard.append("selected-direction: secondary-influence-id 금지(평균 뒷문)")
|
||
# direction-set 바인딩 hash
|
||
if sd.get("direction-set-sha256"):
|
||
_dss = _file_sha(direction_set_path)
|
||
if _dss is None:
|
||
hard.append("selected-direction: direction-set 파일 없음")
|
||
elif _dss != sd["direction-set-sha256"]:
|
||
hard.append("selected-direction: direction-set-sha256 불일치")
|
||
set_ids = {d.get("id") for d in (ds.get("directions") or [])}
|
||
decision = sd.get("selection-decision") or "selected"
|
||
if decision not in ("selected", "none-of-the-above"):
|
||
hard.append(f"selected-direction: selection-decision 값 오류({decision})")
|
||
sel = sd.get("selected-direction-id")
|
||
if decision == "selected" and not sel:
|
||
hard.append("selected-direction: selected 결정은 selected-direction-id 필수")
|
||
if decision == "none-of-the-above" and sel:
|
||
hard.append("selected-direction: none-of-the-above는 selected-direction-id 금지")
|
||
if sel and sel not in set_ids: hard.append(f"selected-direction: 선택 ID {sel} 가 direction-set 에 없음(유령)")
|
||
rej = sd.get("rejected-directions") or []
|
||
rej_ids = {r.get("id") for r in rej if isinstance(r, dict)}
|
||
for r in rej:
|
||
if not (isinstance(r, dict) and str(r.get("reason") or "").strip()): hard.append("selected-direction: rejected reason 필수")
|
||
if isinstance(r, dict) and r.get("id") not in set_ids: hard.append(f"selected-direction: rejected 유령 ID {r.get('id')}")
|
||
# rejected ∪ {selected} == 전체(정확히 덮음)
|
||
classified = rej_ids if decision == "none-of-the-above" else ({sel} | rej_ids)
|
||
if set_ids and classified != set_ids:
|
||
hard.append(f"selected-direction: rejected∪selected 가 전체 방향과 불일치(누락/여분)")
|
||
if sel in rej_ids:
|
||
hard.append("selected-direction: selected 가 rejected 에도 존재(중복 분류)")
|
||
lock = sd.get("locked-invariants") or []
|
||
if decision == "selected" and not (isinstance(lock, list) and len(lock) >= 3):
|
||
hard.append(f"selected-direction: locked-invariants >= 3(현재 {len(lock) if isinstance(lock,list) else 0})")
|
||
if decision == "none-of-the-above" and (lock or sd.get("adopted-elements")):
|
||
hard.append("selected-direction: none-of-the-above는 locked/adopted 요소 금지(평균 금지)")
|
||
ad = sd.get("adopted-elements") or []
|
||
if isinstance(ad, list):
|
||
if len(ad) > 1: hard.append("selected-direction: adopted-elements <= 1")
|
||
for a in ad:
|
||
if not (isinstance(a, dict) and a.get("element-id") and str(a.get("rationale") or "").strip()):
|
||
hard.append("selected-direction: adopted-elements 는 element-id+rationale 필수")
|
||
elif a.get("from-direction-id") not in set_ids:
|
||
hard.append(f"selected-direction: adopted-elements from {a.get('from-direction-id')} 실존 안 함")
|
||
elif any(v in str(a.get("element-id"))+str(a.get("rationale")) for v in _VAGUE):
|
||
hard.append("selected-direction: adopted-elements 포괄표현 금지(원자 element-id만)")
|
||
return (hard, warn)
|
||
|
||
if __name__ == "__main__":
|
||
if sys.argv[1] == "--divergence-bundle":
|
||
h, w = lint_divergence_bundle(sys.argv[2], sys.argv[3], sys.argv[4])
|
||
elif sys.argv[1] == "--bundle":
|
||
h, w = lint_selected_direction(sys.argv[2], sys.argv[3])
|
||
else:
|
||
h, w = lint_file(sys.argv[1], sys.argv[2])
|
||
for x in h: print(f"HARD: {x}")
|
||
for x in w: print(f"WARN: {x}")
|
||
sys.exit(1 if h else 0)
|