pipeline: make tech-log-tree.json the one decomposition contract and enforce it
리뷰 두 건을 반영했다. 계약 - tech-log-tree.json 하나가 분해 계약이자 색인이다. 사람이 읽는 트리·Node Specification· 후보 대장은 없어졌고, 문서에 남아 있던 그 개념을 걷어냈다 - candidateScope — 후보를 찾는 SSOT 범위. 접어 넣은 제2부·제3부는 근거이지 후보가 아니다 - sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 리비전을 모르면 null 로 두고 지어내지 않는다. 갈래가 여럿이면 revisions - 검사기: 계약 미채택·PENDING·PROMOTE↔글감 양방향·candidateScope·sourceRepository 를 error/warn 으로 센다. 옛 스키마도 검사를 피하지 못한다. 테스트 22 → 31 기록 쓰기 - 템플릿 5종에 source·sourceRevision·topicName, Question 에 닫는 조건, 본문 없는 종류에서 assets 제거. 고정 절 개수 삭제 - check_evidence.mjs — 인용한 코드가 SSOT 에 있는지, 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지, 리비전이 저장소에 있는지. 게시된 기록에서 SSOT 와 다른 URL 을 잡았다 문체 - 문체 규칙의 정본을 ai-tells.md 로. explaining.md 의 질문체 제목·절 끝 대조 반복·그림 예고 규칙을 삭제해 충돌을 없앴다. 첫 절 「설명 뒤에 평가를 붙이지 않는다」에 지우는 사례 네 유형 - voice 스킬의 「독자 쪽을 본다」를 자료에 오독 기록이 있을 때로 좁히고, 평가만 더한 예시를 교체 - check_prose: 안내 문장을 요구하던 경고 제거, 문장이 끝나지 않은 채 문단이 끝나는 조각 검사 추가 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
co-authored by
Claude Fable 5.1
Claude Fable 5.1
parent
73026cada6
commit
9d2a3725c5
Executable
+342
@@ -0,0 +1,342 @@
|
||||
#!/usr/bin/env python3
|
||||
"""분해 계약이 스스로 맞는지, 그리고 기록·색인이 계약을 따르는지 본다.
|
||||
|
||||
`verify-pipeline.py` 는 스킬과 틀이 제자리에 있는지만 본다. 이 검사기는 한 프로젝트의
|
||||
실제 트리를 본다 — `tech-log-tree.json` 의 주제·글감·후보와 디스크의 기록이 같은 것을
|
||||
말하는지.
|
||||
|
||||
python3 scripts/verify-tech-log-tree.py [프로젝트 ...] [--strict] [--samples N] [--json]
|
||||
|
||||
정본 순서는 이렇다.
|
||||
|
||||
코드·설정·실행 증거 사실의 근거
|
||||
final/document.md 글감 범위의 SSOT. candidateScope 가 그 범위를 말한다
|
||||
analysis/**/*.md 이미 채택한 주장을 상세 확인하는 보조 근거 (분석 중에만 있다)
|
||||
tech-log-tree.json 사람이 고른 글감. 분해 계약이자 색인이고 정본이다
|
||||
|
||||
error 가 하나라도 있으면 실패다. warn 은 편집 판단이 필요한 자리이고 `--strict` 에서만
|
||||
실패가 된다. 선별을 마치지 않은 상태 — `dispositionReview: PENDING`, PROMOTE 후보와
|
||||
글감이 1:1 이 아닌 것 — 는 warn 이 아니라 error 다. 경고로 두면 재판정하지 않은 트리로
|
||||
글을 쓰기 시작할 수 있다.
|
||||
|
||||
**계약을 아직 채택하지 않은 프로젝트도 error 다.** 칸마다 error 를 내지는 않는다 —
|
||||
「아직 쓰지 않았다」가 「잘못 썼다」로 보이기 때문이다. 대신 계약 미채택 자체를 한 건의
|
||||
error 로 센다. warn 으로 두면 옛 스키마로 남아 있는 한 검사를 영원히 피한다.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import collections
|
||||
import glob
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import sys
|
||||
|
||||
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
|
||||
import techlog # noqa: E402
|
||||
from techlog import KINDS, DISPOSITIONS, READINESS, Report # noqa: E402
|
||||
|
||||
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
|
||||
|
||||
# 종류마다 글감이 반드시 갖는 칸
|
||||
REQUIRED_FIELDS = {
|
||||
"case": ("slug", "readiness", "source", "classification", "missing-verification", "relations"),
|
||||
"concept": ("slug", "readiness", "source", "basis-version", "classification", "relations"),
|
||||
"reference": ("slug", "readiness", "source", "classification", "scope", "exceptions", "relations"),
|
||||
"question": ("slug", "readiness", "source", "known", "unknown",
|
||||
"next-verification", "decision-criterion", "relations"),
|
||||
"decision": ("slug", "readiness", "source", "decision-status", "decision-evidence",
|
||||
"grounds", "classification", "relations"),
|
||||
}
|
||||
# 글을 써도 되는 readiness. 나머지는 글감으로만 남는다
|
||||
GENERATABLE = {"case": {"READY"}, "concept": {"READY"}, "reference": {"READY"},
|
||||
"question": {"OPEN"}, "decision": {"READY"}}
|
||||
DECISION_STATUS = {"PROPOSED", "ADOPTED", "SUPERSEDED", "NOT_DECIDED"}
|
||||
|
||||
# 분석 문서의 절 제목을 그대로 옮겨 온 자리
|
||||
COPIED_HEADING = (
|
||||
(re.compile(r"^\(\d+(?:\.\d+)*\)"), "분석 문서의 절 번호가 제목에 남아 있다"),
|
||||
(re.compile(r"^(Confirmed|P[1-3])\s*[—–-]"), "분석 문서의 finding 등급이 제목에 남아 있다"),
|
||||
)
|
||||
# Concept 은 「남의 것이 어떻게 동작하는가」다
|
||||
CONCEPT_NOT_A_MECHANISM = (
|
||||
(r"없다|없음|부재|미배선|배선되지|호출자|호출되지 않|실행되지 않|도달하지 않", "부재·미배선 사실"),
|
||||
(r"refs?\s*=\s*0|카운트|개수|몇 개|전부 읽|샘플링|denominator", "분석 범위·계수"),
|
||||
(r"보류|남은 것|다음 사이클|이번 pass|커버리지|coverage|레인과 복원|기록이다", "분석 진행 기록"),
|
||||
(r"드리프트|불일치|어긋|틀렸|실패했|누락|검증되지", "Finding 문장"),
|
||||
)
|
||||
|
||||
|
||||
def _front_matter(path: str) -> dict:
|
||||
text = open(path, encoding="utf-8").read()
|
||||
if not text.startswith("---"):
|
||||
return {}
|
||||
end = text.find("\n---", 3)
|
||||
out = {}
|
||||
for line in text[3:end].splitlines():
|
||||
m = re.match(r"^([a-zA-Z_]+):\s*(.*)$", line)
|
||||
if m:
|
||||
out[m.group(1)] = m.group(2).strip().strip('"')
|
||||
return out
|
||||
|
||||
|
||||
def _records_on_disk(studio: str) -> dict[tuple[str, str], str]:
|
||||
found = {}
|
||||
for path in sorted(glob.glob(os.path.join(studio, "*", "*", "*.md"))):
|
||||
parts = path.split(os.sep)
|
||||
topic_dir, kind_dir = parts[-3], parts[-2]
|
||||
if topic_dir.startswith("_") or kind_dir not in KINDS:
|
||||
continue
|
||||
fm = _front_matter(path)
|
||||
found[(kind_dir, fm.get("slug") or os.path.basename(path)[:-3])] = path
|
||||
return found
|
||||
|
||||
|
||||
def _values(node: dict, key: str) -> list[str]:
|
||||
value = node.get(key)
|
||||
if value is None:
|
||||
return []
|
||||
if isinstance(value, list):
|
||||
return [str(v) for v in value if str(v).strip()]
|
||||
return [str(value)] if str(value).strip() else []
|
||||
|
||||
|
||||
def verify(project: str) -> Report:
|
||||
rep = Report(project)
|
||||
base = os.path.join(ROOT, "docs", project)
|
||||
studio = os.path.join(base, "tech-log-studio")
|
||||
records = _records_on_disk(studio)
|
||||
rep.facts["records"] = len(records)
|
||||
|
||||
index_path = os.path.join(studio, "tech-log-tree.json")
|
||||
index = techlog.load_index(index_path)
|
||||
if index is None:
|
||||
rep.warn("분해 계약 없음",
|
||||
f"{project}: tech-log-tree.json 이 없다. 디렉터리가 정본 노릇을 하고 있다")
|
||||
return rep
|
||||
|
||||
# ── 원본 무결성 ────────────────────────────────────────────────
|
||||
ssot_rel = index.get("ssot") or "final/document.md"
|
||||
ssot_path = os.path.join(base, ssot_rel)
|
||||
if not os.path.exists(ssot_path):
|
||||
rep.error("SSOT 파일 없음", ssot_rel)
|
||||
else:
|
||||
declared = index.get("ssotSha256") or ""
|
||||
actual = techlog.sha256_of(ssot_path)
|
||||
if not declared:
|
||||
rep.error("ssotSha256 없음", ssot_rel)
|
||||
elif declared != actual:
|
||||
rep.error("SSOT 가 바뀐 뒤 글감을 다시 보지 않았다",
|
||||
"python3 scripts/build-tech-log-tree.py 를 다시 돌린다")
|
||||
if not index.get("sourceRevision"):
|
||||
rep.warn("sourceRevision 없음", project)
|
||||
|
||||
# 옛 색인은 디렉터리를 훑어 만든 것이라 계약 칸이 아예 없다. 칸마다 error 를 내면
|
||||
# 「아직 쓰지 않았다」가 「잘못 썼다」로 보인다
|
||||
has_contract = index.get("schemaVersion", 1) >= 4 or "contract" in index
|
||||
rep.facts["contract"] = "있음" if has_contract else "없음"
|
||||
if not has_contract:
|
||||
rep.error("글감 계약을 아직 쓰지 않았다",
|
||||
f"{project}: 옛 색인이다. 주제·독자 질문·글감의 칸을 사람이 적어야 한다 "
|
||||
"— 칸마다 error 를 내지 않는 대신 미채택 자체를 여기서 한 번 센다")
|
||||
|
||||
# ── 분석한 저장소 ──────────────────────────────────────────────
|
||||
repo = index.get("sourceRepository") or {}
|
||||
if has_contract:
|
||||
if not repo.get("path"):
|
||||
rep.error("sourceRepository.path 가 없다",
|
||||
f"{project}: 어느 저장소를 읽고 쓴 글인지 적혀 있지 않다")
|
||||
elif not os.path.isdir(repo["path"]) and "://" not in repo["path"]:
|
||||
rep.warn("sourceRepository.path 가 이 기계에 없다", repo["path"])
|
||||
# 갈래가 여럿이면 단일 커밋으로 표현되지 않는다. revisions 로 적는다
|
||||
if not repo.get("revision") and not repo.get("revisions"):
|
||||
rep.warn("sourceRepository 에 리비전이 없다",
|
||||
f"{project}: 문서가 서술한 상태의 커밋을 고정하지 않았다")
|
||||
elif not repo.get("verified"):
|
||||
rep.warn("sourceRepository.verified 가 없다",
|
||||
f"{project}: 그 리비전이 맞다고 판단한 근거가 없다")
|
||||
|
||||
# ── 후보를 찾는 범위 ───────────────────────────────────────────
|
||||
scope = index.get("candidateScope") or {}
|
||||
excluded_anchor = None
|
||||
if has_contract:
|
||||
if not scope:
|
||||
rep.error("candidateScope 가 없다",
|
||||
f"{project}: SSOT 의 어느 부분에서 후보를 찾는지 적지 않았다")
|
||||
else:
|
||||
if scope.get("document") and scope["document"] != ssot_rel:
|
||||
rep.error("candidateScope.document 가 ssot 과 다르다",
|
||||
f"{scope['document']} ≠ {ssot_rel}")
|
||||
if not scope.get("sections"):
|
||||
rep.error("candidateScope 에 sections 가 없다", project)
|
||||
pattern = scope.get("excludedAnchorPattern")
|
||||
if pattern:
|
||||
try:
|
||||
excluded_anchor = re.compile(pattern)
|
||||
except re.error as exc:
|
||||
rep.error("candidateScope.excludedAnchorPattern 이 정규식이 아니다",
|
||||
f"{pattern} — {exc}")
|
||||
|
||||
# ── 주제 ───────────────────────────────────────────────────────
|
||||
topics = index.get("topics") or {}
|
||||
rep.facts["topics"] = len(topics)
|
||||
for slug, topic in topics.items():
|
||||
if topic.get("topic") and topic["topic"] != slug:
|
||||
rep.error("주제 키와 topic 이 다르다", f"{slug} ≠ {topic['topic']}")
|
||||
if not (topic.get("readerQuestion") or "").strip():
|
||||
if has_contract:
|
||||
rep.error("Topic 에 독자 질문이 없다", slug)
|
||||
elif not topic["readerQuestion"].rstrip().endswith("?"):
|
||||
rep.warn("독자 질문이 물음이 아니다", f"{slug}: {topic['readerQuestion'][:60]}")
|
||||
n = sum(len(v) for v in (topic.get("kinds") or {}).values())
|
||||
if n == 1:
|
||||
rep.warn("Topic 에 노드가 하나뿐이다", slug)
|
||||
if n == 0:
|
||||
rep.error("Topic 에 글감이 없다", slug)
|
||||
|
||||
# ── 글감 ───────────────────────────────────────────────────────
|
||||
slugs: dict[str, str] = {}
|
||||
listed: set[tuple[str, str]] = set()
|
||||
total = 0
|
||||
for topic_slug, kind, node in techlog.nodes(index):
|
||||
total += 1
|
||||
where = f"{topic_slug} · {kind.upper()} · {str(node.get('title',''))[:44]}"
|
||||
if kind not in REQUIRED_FIELDS:
|
||||
rep.error("종류 이름이 계약에 없다", f"{where} — {kind}")
|
||||
continue
|
||||
if has_contract:
|
||||
for key in REQUIRED_FIELDS[kind]:
|
||||
if not _values(node, key):
|
||||
rep.error(f"{kind.upper()} 노드에 `{key}` 가 없다", where)
|
||||
slug = str(node.get("slug") or "")
|
||||
if slug:
|
||||
if slug in slugs:
|
||||
rep.error("slug 가 두 글감에 있다", f"{slug} — {slugs[slug]} / {where}")
|
||||
slugs[slug] = where
|
||||
listed.add((kind, slug))
|
||||
readiness = str(node.get("readiness") or "").upper()
|
||||
if readiness and readiness not in READINESS:
|
||||
rep.error("readiness 값이 계약에 없다", f"{where} — {readiness}")
|
||||
if kind == "question" and readiness and readiness != "OPEN":
|
||||
rep.error("OPEN QUESTION 의 readiness 는 OPEN 이다", f"{where} — {readiness}")
|
||||
if kind == "decision":
|
||||
status = str(node.get("decision-status") or "").strip("`").upper()
|
||||
if status and status not in DECISION_STATUS:
|
||||
rep.error("decision-status 값이 계약에 없다", f"{where} — {status}")
|
||||
if has_contract and not _values(node, "relations"):
|
||||
rep.warn("관계가 없는 노드", where)
|
||||
anchors = " ".join(_values(node, "source"))
|
||||
if anchors and ssot_rel not in anchors:
|
||||
rep.warn("근거가 SSOT 밖에만 있다", f"{where} — {anchors[:60]}")
|
||||
if excluded_anchor:
|
||||
outside = [a for a in _values(node, "source") if excluded_anchor.search(a)]
|
||||
if outside and len(outside) == len(_values(node, "source")):
|
||||
rep.error("후보를 찾는 범위 밖에서만 나온 글감",
|
||||
f"{where} — {outside[0][:60]}")
|
||||
title = str(node.get("title") or "")
|
||||
for pattern, why in COPIED_HEADING:
|
||||
if pattern.match(title):
|
||||
rep.warn(why, where)
|
||||
break
|
||||
if kind == "concept":
|
||||
for pattern, why in CONCEPT_NOT_A_MECHANISM:
|
||||
if re.search(pattern, title):
|
||||
rep.warn(f"Concept 제목이 메커니즘이 아니다 — {why}", where)
|
||||
break
|
||||
rep.facts["nodes"] = total
|
||||
|
||||
# ── readiness ↔ 실제로 쓴 글 ───────────────────────────────────
|
||||
written = 0
|
||||
for (kind, slug), path in sorted(records.items()):
|
||||
rel = os.path.relpath(path, ROOT)
|
||||
if (kind, slug) not in listed:
|
||||
rep.error("계약에 없는 기록", rel)
|
||||
continue
|
||||
written += 1
|
||||
node = next((n for _, k, n in techlog.nodes(index)
|
||||
if k == kind and n.get("slug") == slug), None)
|
||||
readiness = str((node or {}).get("readiness") or "").upper()
|
||||
if readiness and readiness not in GENERATABLE[kind]:
|
||||
rep.error("글을 쓰면 안 되는 readiness 인데 기록이 있다",
|
||||
f"{rel} — readiness={readiness}")
|
||||
rep.facts["written"] = written
|
||||
rep.facts["unwritten"] = total - written
|
||||
|
||||
# ── 후보와 처분 ────────────────────────────────────────────────
|
||||
candidates = index.get("candidates") or []
|
||||
if candidates:
|
||||
counts = collections.Counter()
|
||||
promoted: set[str] = set()
|
||||
for c in candidates:
|
||||
d = c.get("disposition")
|
||||
counts[d] += 1
|
||||
if d not in DISPOSITIONS:
|
||||
rep.error("disposition 값이 계약에 없다", f"{c.get('id')} — {d}")
|
||||
if c.get("dispositionReview") != "CONFIRMED":
|
||||
rep.error("disposition 을 다시 판정하지 않은 후보",
|
||||
f"{c.get('id')} — 선별이 아니라 recall 로 방출됐다")
|
||||
if d == "PROMOTE":
|
||||
target = c.get("target") or ""
|
||||
slug = target.split(":", 1)[1] if ":" in target else target
|
||||
if not slug:
|
||||
rep.error("PROMOTE 후보에 target 이 없다", str(c.get("id")))
|
||||
continue
|
||||
promoted.add(slug)
|
||||
if slug not in slugs:
|
||||
rep.error("PROMOTE 후보가 글감에 없다", f"{c.get('id')} → {target}")
|
||||
rep.facts["candidates"] = dict(counts)
|
||||
# 반대 방향 — 후보 대장을 거치지 않고 트리에 올라온 글감
|
||||
for slug, where in sorted(slugs.items()):
|
||||
if slug not in promoted:
|
||||
rep.error("글감을 낳은 PROMOTE 후보가 없다", f"{slug} — {where}")
|
||||
return rep
|
||||
|
||||
|
||||
def render(rep: Report, samples: int) -> None:
|
||||
facts = " · ".join(
|
||||
f"{k}={json.dumps(v, ensure_ascii=False) if isinstance(v, dict) else v}"
|
||||
for k, v in rep.facts.items())
|
||||
print(f"\n[{rep.project}] {facts}")
|
||||
for label, bucket, mark in (("error", rep.errors, "✗"), ("warn", rep.warns, "!")):
|
||||
for rule, details in sorted(bucket.items(), key=lambda kv: -len(kv[1])):
|
||||
print(f" {mark} {label} {len(details):>4} {rule}")
|
||||
for d in details[:samples]:
|
||||
if d:
|
||||
print(f" · {d}")
|
||||
if samples and len(details) > samples:
|
||||
print(f" … 외 {len(details) - samples}건")
|
||||
|
||||
|
||||
def main() -> int:
|
||||
ap = argparse.ArgumentParser(description="한 프로젝트의 글감 계약 정합성을 본다.")
|
||||
ap.add_argument("projects", nargs="*")
|
||||
ap.add_argument("--samples", type=int, default=3)
|
||||
ap.add_argument("--strict", action="store_true", help="warn 도 실패로 센다")
|
||||
ap.add_argument("--json", action="store_true")
|
||||
args = ap.parse_args()
|
||||
|
||||
projects = args.projects or sorted(
|
||||
name for name in (
|
||||
os.path.basename(os.path.dirname(p))
|
||||
for p in glob.glob(os.path.join(ROOT, "docs/*/tech-log-studio"))
|
||||
) if not name.startswith("_")
|
||||
)
|
||||
reports = [verify(p) for p in projects]
|
||||
if args.json:
|
||||
print(json.dumps([{"project": r.project, "facts": r.facts,
|
||||
"errors": dict(r.errors), "warns": dict(r.warns)}
|
||||
for r in reports], ensure_ascii=False, indent=2))
|
||||
return 1 if sum(r.error_count for r in reports) else 0
|
||||
|
||||
for r in reports:
|
||||
render(r, args.samples)
|
||||
e = sum(r.error_count for r in reports)
|
||||
w = sum(r.warn_count for r in reports)
|
||||
print(f"\nTECH LOG TREE: {'FAIL' if e or (args.strict and w) else 'PASS'}"
|
||||
f" — 프로젝트 {len(reports)} · error {e} · warn {w}")
|
||||
return 1 if e or (args.strict and w) else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Reference in New Issue
Block a user