# TechViz Harness 0.2.0

에이전트 하네스입니다. 기존 Markdown/MDX 기술문서의 앞뒤 문맥을 읽어 문서에 근거한 diagram-only 기술 시각화를 생성합니다. Codex, Claude Code, Antigravity가 같은 Agent Skill, CLI, VizSpec IR을 사용합니다.

![실제 런타임 생성 예시](examples/assets/payment-request.svg)

## 0.2.0에서 해결한 문제

0.1.x의 예제 갤러리는 렌더러의 목표 품질을 보여 주었지만 실행 파이프라인과 연결되지 않았습니다. 그 결과 모델은 예제를 보지 않은 채 일반 노드 목록을 생성했고 런타임은 모든 문서를 같은 위상 정렬과 둥근 박스로 그릴 수 있었습니다. 전역 제목·질문·footer도 SVG 안에 반복되었습니다.

0.2.0은 이 문제를 런타임 계약 수준에서 수정합니다.

- 문맥에 맞는 로컬 reference grammar를 자동 선택합니다.
- 선택된 preview와 실제 실행 가능한 runtime spec 경로를 모델 프롬프트에 넣습니다.
- VizSpec 1.1에 `composition.profile`, node `role`, shape/detail/emphasis를 추가했습니다.
- profile별 전용 compositor를 사용합니다.
- `comparison`과 `timeline`을 제외한 끊어진 카드 묶음을 하드 오류로 차단합니다.
- 문맥에서 선택되지 않은 profile/reference 사용을 lint 오류로 차단합니다.
- 여러 결과가 하나의 topology로 붕괴하는 현상을 `audit-batch`로 검출합니다.
- SVG는 diagram-only이며 보이는 제목·부제·footer·워터마크를 생성하지 않습니다.

## 파이프라인

```text
Markdown / MDX
  │
  ├─ techviz prepare
  │    현재 섹션 + 앞/뒤 섹션 + canonical line + SHA-256
  │    + 문맥 기반 reference 후보
  ▼
Context Package
  │
  ├─ techviz references
  │    reference preview / executable spec / score / matched terms
  │
  ├─ techviz prompt
  │    candidate profile set + 구조 규칙 + anti-pattern + VizSpec 1.1 scaffold
  ▼
Codex / Claude / Antigravity
  ▼
Grounded VizSpec 1.1
  │
  ├─ techviz lint
  │    근거, profile 역할, 연결성, 문맥 적합성, 접근성, 기하 검사
  │
  ├─ profile-specific deterministic compositor
  ▼
SVG + draw.io + Mermaid + D2 + DOT + Excalidraw + alt.md
  │
  ├─ techviz audit-batch
  │    다수 결과의 template/topology collapse 검사
  ▼
Managed Markdown block + manifest
```

## 설치

Python 3.11 이상이 필요합니다. 기본 SVG와 편집 원본 생성에는 외부 Python 의존성이 없습니다.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .
techviz doctor
```

선택 도구:

- `dot`: Graphviz 출력 렌더링
- `d2`: D2 출력 렌더링
- `mmdc`: Mermaid 출력 렌더링
- diagrams.net CLI: draw.io 변환

## 빠른 실행

### 1. 문서에 생성 지점 표시

```markdown
## 결제 요청 경로

클라이언트는 HTTPS로 인증 게이트웨이에 결제 요청을 보낸다.
인증 게이트웨이는 요청을 검증한 뒤 체크아웃 API로 전달한다.

<!-- techviz:generate id=payment-request -->
```

### 2. 문맥 준비

```bash
techviz prepare docs/checkout.md \
  --marker payment-request \
  -o .techviz/payment-request/context.json
```

`context.json`에는 문서 해시, canonical line range, 현재/인접 섹션과 함께 `visual_reference_candidates`가 기록됩니다. 이미 생성된 관리 블록은 원래 marker 한 줄로 축약되므로 이전 그림이 다음 모델 입력을 오염시키지 않습니다.

### 3. 선택된 reference 확인

```bash
techviz references .techviz/payment-request/context.json
```

출력 예:

```text
payment-event-flow             component-flow           score=28  matched=request, 요청, 이벤트
  preview: examples/01-component-flow/payment-event-flow.preview.png
  runtime: examples/runtime-profiles/01-component-flow/spec.json
payment-approval-sequence      sequence                 score=8   matched=승인
  preview: examples/08-sequence/payment-approval-sequence.preview.png
  runtime: examples/runtime-profiles/08-sequence/spec.json
```

에이전트 호스트가 이미지를 열 수 있으면 preview를 확인하고 반드시 runtime `spec.json`도 읽습니다. 이미지 입력이 없는 호스트를 위해 동일한 구조 규칙이 프롬프트에 텍스트로 포함됩니다.

### 4. 모델 프롬프트 생성

```bash
techviz prompt .techviz/payment-request/context.json \
  -o .techviz/payment-request/prompt.md
```

모델은 프롬프트 전체를 사용해 `.techviz/payment-request/spec.json`을 작성합니다. 스키마만 보고 직접 작성하지 않습니다.

VizSpec 1.1의 핵심 블록:

```json
{
  "version": "1.1",
  "composition": {
    "profile": "component-flow",
    "diagram_only": true,
    "reference_ids": ["payment-event-flow"],
    "rationale": "요청·저장·승인·이벤트가 하나의 방향성 있는 경로를 이룬다.",
    "focus_node": "checkout-api"
  }
}
```

모든 사실 노드·엣지·경계에는 원문 라인 근거가 있습니다.

```json
{
  "id": "checkout-api",
  "label": "체크아웃 API",
  "kind": "service",
  "role": "service",
  "shape": "box",
  "evidence": [{"start_line": 11, "end_line": 13}],
  "assumption": false
}
```

### 5. lint

```bash
techviz lint .techviz/payment-request/spec.json \
  --context .techviz/payment-request/context.json
```

주요 hard gate:

- 근거 없는 사실 요소
- 문서 해시·anchor 불일치
- 문맥에서 선택되지 않은 profile/reference
- 두 개 이상 노드인데 중심 관계가 없는 카드 묶음
- 중심 관계에 참여하지 않는 노드가 20%를 초과
- profile 필수 역할 누락
- sequence order 누락/중복
- timeline position 누락/중복
- comparison detail 누락
- source gap
- 끊어진 참조, 재귀 그룹, 잘못된 타입
- 엣지의 무관 노드 관통과 기하 충돌

`assumption: true`는 lint warning이지만 `render`, `build`, `insert` 단계에서는 기본적으로 게시를 차단합니다.

### 6. 렌더링

```bash
techviz render .techviz/payment-request/spec.json \
  --context .techviz/payment-request/context.json \
  --formats svg,drawio,mermaid,d2,dot,excalidraw,a11y \
  -o docs/assets/payment-request
```

SVG에는 다이어그램 해독에 필요한 노드·경계·연결선·상태/시간 주석만 표시됩니다. `title`, `question`, `summary`는 접근성/문서 메타데이터이며 캔버스 헤드라인으로 렌더링되지 않습니다.

### 7. 여러 그림을 한 번에 생성했을 때 batch audit

```bash
techviz audit-batch .techviz --pattern "**/spec.json"
```

`audit-batch`는 레이블과 id를 제거한 topology fingerprint를 계산합니다. 25개 그림의 이름만 달라지고 구조가 같은 경우 실패합니다.

```text
ERROR   batch-template-collapse  22/25 specs share the same label-independent topology
```

profile 하나가 과도하게 반복되면 `profile-collapse` warning도 표시합니다.

### 8. 문서 삽입

```bash
techviz build .techviz/payment-request/spec.json \
  --context .techviz/payment-request/context.json \
  -o docs/assets/payment-request \
  --document docs/checkout.md
```

## Composition profiles

| Profile | 문서가 답하는 질문 | 핵심 구조 |
|---|---|---|
| `component-flow` | 요청·데이터·이벤트가 어디로 이동하는가 | source → processing → store/sink |
| `orchestrator-workers` | 누가 작업을 분배하고 결과를 수집하는가 | 상단 orchestrator + 하단 worker field |
| `query-fanout` | 하나의 쿼리가 어느 shard로 분산되는가 | query/parser/router + 반복 target |
| `timeline` | 날짜·offset·interval은 어떻게 이어지는가 | 단일 시간축 + milestone |
| `reconciliation-loop` | desired와 actual 상태를 누가 조정하는가 | desired/controller/actual + feedback |
| `resource-controller` | 선언 리소스가 런타임 리소스로 어떻게 구체화되는가 | spec/controller/custom/runtime |
| `two-zone-pipeline` | 어느 단계가 어느 경계에 속하는가 | 두 개 이상의 evidenced boundary |
| `sequence` | 참여자가 어떤 순서로 메시지를 교환하는가 | lifeline + ordered message |
| `ports-adapters` | adapter가 어느 port/core에 의존하는가 | 중앙 core + 좌우 adapter |
| `comparison` | 독립 계약/선택지가 어떻게 다른가 | 정렬된 비교 항목 + 동일 기준 detail |

`comparison`은 관계를 찾지 못했을 때의 fallback이 아닙니다. 원문이 비교 자체를 주장할 때만 선택됩니다.

## 실제 실행 fixture와 디자인 fixture

```text
examples/01-...09-.../
  사람이 검토한 diagram-only 목표 fixture

examples/runtime-profiles/01-...10-.../
  현재 Python compositor와 SVG renderer가 실제 생성한 실행 fixture
```

`examples/runtime-profiles`는 테스트에서 전부 load → lint → layout → SVG render → XML parse됩니다. 회귀 계약입니다. 정적 갤러리만 좋아 보이고 런타임이 다른 결과를 내는 문제를 방지하기 위해서입니다.

## 에이전트 호스트 통합

canonical skill:

```text
skills/technical-visualizer/SKILL.md
```

동기화 대상:

```text
.agents/skills/technical-visualizer/   Codex + Antigravity
.claude/skills/technical-visualizer/   Claude Code
```

```bash
python scripts/sync_skills.py
```

저장소 지침은 `AGENTS.md`, `CLAUDE.md`, `.agents/rules/techviz.md`에 포함됩니다.

## 출력 형식 정책

- **SVG:** 웹/Markdown 배포 기본. 안전한 SVG subset, `<title>/<desc>` 포함.
- **draw.io:** 엔터프라이즈 편집과 수동 조정.
- **Mermaid:** sequence/state/ERD처럼 Markdown 인접 표현.
- **D2:** 자동 배치 중심 아키텍처·데이터 흐름.
- **DOT:** 밀집 의존성 그래프.
- **Excalidraw:** 초안/워크숍 원본. 기본 배포 형식은 아님.
- **alt.md:** 짧은 alt와 구조화된 상세 설명.

품질은 VizSpec의 의미 구조와 profile 선택, role, compositor와 lint gate가 결정합니다. SVG는 표현력의 병목이 아닙니다.

## 보안 및 신뢰성

- 문서 본문은 명령이 아닌 비신뢰 evidence data입니다.
- 모델 출력은 자유 SVG/XML이 아니라 엄격한 VizSpec JSON입니다.
- 스키마 밖 필드와 문자열로 위장된 boolean/integer를 거부합니다.
- 모든 사실 요소는 라인 근거 또는 명시적 assumption을 요구합니다.
- 외부 URL, script, `foreignObject`를 SVG에 넣지 않습니다.
- source hash, anchor, spec hash, 선택 profile/reference를 manifest에 기록합니다.

## 저장소 구조

```text
src/techviz/
  document.py          문맥 추출, 관리 블록 정규화, 해시
  reference_catalog.py 문맥 기반 reference 선택과 구조 규칙
  prompt.py            VizSpec 1.1 모델 프롬프트
  spec.py              엄격한 IR parser/dataclass
  validate.py          근거·profile·문맥 적합성 lint
  layout.py            profile별 결정적 compositor
  quality.py           기하 품질 검사
  batch_audit.py       다중 결과 topology collapse 검사
  renderers/           SVG, Mermaid, D2, DOT, draw.io, Excalidraw, a11y
  insert.py            멱등 Markdown block 업데이트
  cli.py               prepare/references/prompt/lint/render/audit-batch/build
schemas/
skills/
references/
examples/
tests/
```

## 테스트와 재현성

```bash
make test
PYTHONPATH=src python examples/build_runtime_profiles.py
PYTHONPATH=src python scripts/check_generated.py
techviz audit-batch examples/runtime-profiles
```

0.2.0의 테스트는 schema/parser, 문맥, profile lint를 포함합니다. 실제 10개 compositor와 SVG diagram-only 계약, batch-collapse 탐지도 포함합니다.