# Content Harness
Content Harness는 자연어 기반 콘텐츠 요청을 문서 계획, 정확한 기술 시각화, 유기적 이미지 생성, 검토된 publication output으로 연결하는 provider-neutral Python 시스템입니다.
문서 작성과 기술 도형, 유기적 이미지에는 서로 다른 생성·검토 기준이 필요합니다. 이 저장소는 세 production harness를 sibling으로 유지하고, `workflow-runtime`만 라우팅·DAG 실행·결과 전달·publication을 조정하도록 책임을 나눕니다.
이 README는 저장소를 처음 평가하는 개발자에게는 실행 가능한 contract chain을, 기여자에게는 capability별 변경 위치를, 리뷰어에게는 실제 생성 산출물과 현재 qualification 한계를 보여줍니다.
## 책임이 섞이지 않는 네 capability
### Document Writing
`document-writing`은 독자·서사·근거 연결·시각화 기회를 다루고, ContentJobRequest·Content Manifest·Narrative Plan·publication draft·Visual Request를 만듭니다. 원문을 제자리에서 덮어쓰거나 renderer와 image provider를 선택하지 않습니다.
### Technical Visualization
`technical-visualization`은 근거에 묶인 semantic model, visual grammar, D2 렌더링, 문서·발표용 rendition을 소유합니다. 현재 실행 가능한 visual type은 `dependency-graph`와 `runtime-sequence`이며, accepted ArtifactSet에는 서로 다른 reviewer가 작성한 technical-semantic·technical-visual review가 필요합니다.
### Image Generation
`image-generation`은 사진·일러스트·재질·분위기 같은 organic raster를 소유합니다. production 경로는 해시된 후보 3개, pairwise comparison, 명시적 선택, 최대 한 번의 bounded repair를 사용하며, exact architecture relation·chart·state machine·긴 정확 텍스트는 이 capability의 범위 밖입니다.
### Workflow Runtime과 Integrations
`workflow-runtime`은 contract validation, routing, cycle-free DAG, freshness, retry, immutable result 수집, integration dispatch, event와 portable output publication을 소유합니다. sibling harness는 서로를 직접 호출하지 않습니다.
Markdown·Slides·HTML adapter는 runtime이 선택해 동결한 publication projection 하나만 소비하며, 내용·관점·route·renderer·provider를 다시 결정하지 않습니다.
## 2분 검증
### 전제 조건
핵심 contract와 runtime은 Python 3에서 동작하며 PyYAML과 jsonschema를 사용합니다. Raster 검증·preview에는 Pillow가, technical rendering에는 D2가, SVG의 browser preview에는 Chrome 또는 Chromium이 필요합니다. 저장소는 이 도구들의 버전을 고정하지 않습니다.
현재 저장소에는 `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg`, `Pipfile`, `poetry.lock`, `uv.lock`이 없어 하나의 정본 설치 명령을 제시할 수 없습니다. 필요한 도구를 환경에 준비한 뒤 아래 검증을 실행하십시오.
### 1. 자연어 요청의 contract 확인
```bash
python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
```
이 명령은 이번 README 작성 세션에서 exit code 0으로 완료됐습니다. 출력 없이 종료되면 체크인된 ContentJobRequest가 현재 contract를 통과한 것입니다.
### 2. Front door 계획 확인
```bash
python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
```
이 명령도 exit code 0으로 완료됐고 `primary_capability: document-writing`인 plan을 출력했습니다. 이는 계획 단계의 확인이며 author·review provider를 호출하는 production 실행은 아닙니다.
## 요청에서 publication까지
Contract chain은 `ContentJobRequest` → `Content Manifest` → `Narrative Plan` → `Visual Request` → `ArtifactSet` → frozen publication projection 순서로 책임을 좁혀 갑니다. JSON Schema는 구조를, Python validator는 현재 파일 hash·safe path·cross-contract ID·evidence·routing·freshness처럼 schema만으로 표현하기 어려운 조건을 확인합니다.
Visual Request의 신호가 technical-only이면 `technical-visualization`, image-only이면 `image-generation`, 둘 다이면 runtime-owned hybrid DAG로 라우팅됩니다. 신호가 없으면 `BLOCKED_UNRESOLVED`, 명시적 충돌이면 `ROUTING_CONFLICT`입니다.
각 harness는 plan 또는 immutable JobResult를 runtime에 반환합니다. Runtime만 sibling 결과를 조립하고 accepted rendition의 publication projection을 동결해 integration adapter로 넘깁니다.
Deterministic validation은 expert review를 대신하지 않습니다. 필수 review가 없는 유효한 technical 결과는 `produced`에 머물며 `accepted`나 integration-ready로 승격되지 않습니다.
다음 흐름은 request와 contract가 runtime에서 sibling capability로 분기한 뒤 reviewed draft 또는 accepted ArtifactSet으로 합류하는 지점을 요약합니다.
```mermaid
flowchart LR
A["자연어 요청"] --> B["ContentJobRequest / Visual Request"]
B --> R{"workflow-runtime
routing · DAG · freshness"}
R --> D["document-writing"]
R --> T["technical-visualization"]
R --> I["image-generation"]
T --> H["runtime-owned
hybrid composition"]
I --> H
D --> O["reviewed publication draft"]
T --> S["accepted ArtifactSet"]
I --> S
H --> S
O --> P["frozen publication projection"]
S --> P
P --> G["Markdown · Slides · HTML"]
```
## 생성 산출물 둘러보기
### 버전 관리되는 contract example
[Clean Architecture 예제](examples/clean-architecture/)는 ContentJobRequest부터 Visual Request와 ArtifactSet까지 이어지는 체크인된 contract chain입니다. `artifact/attempt-01/`에는 document·presentation·reveal-step SVG와 `accepted`/`ready` 상태의 manifest가 있지만, 이는 renderer-backed golden이 아니라 최소 contract fixture입니다.
- [ArtifactSet manifest](examples/clean-architecture/artifact/attempt-01/artifact-set.yaml)
- [문서용 SVG fixture](examples/clean-architecture/artifact/attempt-01/dependency-directions.svg)
- [발표용 SVG fixture](examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation.svg)
### 현재 작업 사본의 로컬 테스트 산출물
현재 작업 사본에는 문서 작성·기술 시각화·이미지 생성을 함께 통과시킨 로컬 P6 결과가 있습니다. `runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/` 아래에는 `final-document.md`, `index.html`, 전체 문서 `preview.png`, 문서·발표용 dependency-direction SVG, organic PNG 두 target, image candidate contact sheet와 validation manifest가 있습니다.
문서와 기술 시각화를 함께 시험한 `runs/docvis-20260716-executable-clean-architecture-part1/`에는 통합 HTML, desktop·mobile 문서 preview, 두 figure의 target별 SVG와 PNG fallback, delivery·asset manifest가 있습니다.
Best-of-three 이미지 예제인 `runs/img-20260716-japanese-animation-test/`는 3개 후보 중 attempt 2를 `BEST_OF_N_PASS`로 선택하고 `outputs/final-selected.png`를 남겼습니다.
| 산출물 유형 | 로컬 예시 | 확인할 것 |
| --- | --- | --- |
| 생성 문서 | `output/final-document.md`, `output/index.html`, `output/preview.png` | Markdown·HTML·전체 페이지 preview와 delivery manifest |
| 기술 시각화 | `assets/dependency-directions.document.svg`, `assets/dependency-directions.presentation.svg` | 같은 semantic source의 target별 크기·표현 |
| 생성 이미지 | `assets/editorial-workbench.document.png`, `assets/editorial-workbench.presentation.png` | target별 organic rendition과 선택된 candidate hash |
| 비교·검토 자료 | `assets/image-candidates.png`, `validation-summary.yaml` | 후보 contact sheet와 capability별 validation 결과 |
`runs/**`는 `.gitignore` 대상인 로컬 immutable 실행 작업공간이며 cache나 source of truth가 아닙니다. 새 실행은 `runs//run--NNN/`을 할당하고, reviewed deliverable이 있으면 `/output/index.html`과 hash-bound `manifest.yaml`을 만들 수 있습니다.
따라서 위 로컬 PNG·SVG를 README에 직접 임베드하지 않았습니다. GitHub에서 지속되는 gallery가 필요하면 검토된 파일을 `examples/` 또는 별도 versioned 문서 asset 경로로 승격하고, provenance와 manifest를 함께 갱신해야 합니다.
자세한 실행 데이터 정책은 [Runtime workspace](runs/README.md)를 참고하십시오.
## 저장소 구조와 변경 위치
| 경로 | 정본 책임 | 변경할 때 함께 볼 곳 |
| --- | --- | --- |
| `.agents/`, `.codex/` | AI 도구의 thin discovery adapter | 해당 capability의 `harnesses/` 정본 |
| `harnesses/` | document·technical visual·image capability 정책과 구현 | `packages/` contract, capability test |
| `packages/` | contract, schema support, workflow runtime | schema fixture, conformance·runtime test |
| `integrations/` | frozen projection을 받는 Markdown·Slides·HTML adapter | publication adapter test |
| `tests/` | conformance, contract, runtime, failure injection, E2E | `tests/golden/` regression oracle |
| `examples/` | versioned executable contract chain | validator와 example manifest |
| `benchmarks/` | suite, failure corpus, qualification result | policy의 qualification 상태 |
| `runs/` | ignored local execution data | `runs/README.md`; 정본으로 사용 금지 |
이 소유권 지도에서 `.agents/.codex`는 adapter, `harnesses`는 capability 구현, `packages`는 contract와 runtime, `integrations`는 publication target을 담당합니다.
정본 의존 방향은 adapter → harnesses → packages이며, `workflow-runtime`은 handler registry를 통해 harness를 실행하고 frozen projection만 integrations로 보냅니다. Contract와 integration adapter가 harness implementation을 역으로 소유하지 않습니다.
구체적인 contract chain과 hybrid composition 경계는 [ARCHITECTURE.md](ARCHITECTURE.md)에 있습니다.
## 검증 명령과 증거 수준
이번 README 작업에서는 다음 세 검증도 저장소 루트에서 실제 실행했습니다.
```bash
python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
```
결과: `VALID`, exit code 0.
```bash
python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
```
결과: `VALID`, exit code 0. 이 검증은 체크인된 contract fixture를 대상으로 하며 fresh renderer execution을 대신하지 않습니다.
```bash
python3 -m unittest tests.conformance.test_repository_layout
```
결과: 18개 test가 통과했습니다. 이 범위는 canonical directory와 adapter boundary를 확인하며 전체 suite를 대신하지 않습니다.
전체 discovery 명령은 다음과 같이 정의돼 있습니다.
```bash
python3 -m unittest discover -s tests -p 'test_*.py'
```
전체 suite는 이번 README 작업에서 재실행하지 않았습니다. [2026-07-18 refactoring review](docs/refactoring-review.md#verification-performed)는 별도의 300-test pass를 기록하지만, 이를 이번 실행 결과로 재표현하지 않습니다.
Renderer-backed E2E는 외부 Java/Gradle evidence repository, 외부 source document 또는 scope별 expert review 파일을 요구합니다. exact run root를 단계 사이에 전달하는 명령은 [End-to-end workflows](tests/end-to-end/README.md)에 분리돼 있습니다.
## 현재 상태와 한계
- **설치 재현성:** dependency packaging manifest와 version pin이 없으므로 README는 임의의 패키지 설치 명령이나 최소 버전을 만들지 않습니다.
- **산출물 지속성:** 실제 PNG·SVG·HTML·Markdown 샘플은 로컬 `runs/`에 있지만 clean checkout이나 GitHub 링크의 영속성을 보장하지 않습니다.
- **Benchmark 성숙도:** document-writing과 image-generation suite는 corpus만 정의되고 결과가 pending입니다. Technical visualization의 dependency-direction 비교도 일부 condition과 human preference가 남아 있습니다.
- **Hybrid qualification:** `d2-svg-layer-compositor`의 자동 16-case 증거는 PASS지만 human Gate 3는 `PENDING`입니다. 이 renderer는 qualification candidate이며 qualified renderer로 소개하면 안 됩니다.
- **E2E 입력:** 전체 품질·dependency-direction·redraw 경로는 이 저장소만으로 완결되지 않고 외부 evidence/source와 완료된 expert review를 요구합니다.
## 문서와 정본 지도
정본 설계는 `ARCHITECTURE.md`, 문서 색인은 `docs/README.md`, 실행 작업공간 정책은 `runs/README.md`에 있습니다.
- [Architecture](ARCHITECTURE.md) — layering, contract chain, routing, review authority, run identity
- [Documentation map](docs/README.md) — 현재 문서와 historical implementation 기록의 구분
- [Runtime workspace](runs/README.md) — fresh allocation, exact resume, output publication
- [Document Writing Harness](harnesses/document-writing/README.md)
- [Technical Visualization Harness](harnesses/technical-visualization/README.md)
- [Image Generation Harness](harnesses/image-generation/README.md)
- [Workflow Runtime](packages/workflow-runtime/README.md)
- [Clean Architecture example](examples/clean-architecture/)
- [End-to-end workflows](tests/end-to-end/README.md)
- [Benchmarks](benchmarks/technical-visualization/README.md) · [image quality](benchmarks/image-quality/README.md) · [hybrid composition](benchmarks/hybrid-composition/README.md)
과거 phase 문서는 구현 이력일 뿐 현재 capability 정의가 아닙니다. 현재 동작을 바꿀 때는 위 정본과 관련 contract·test·benchmark를 함께 갱신하십시오.