379 lines
27 KiB
Diff
379 lines
27 KiB
Diff
--- README.md (current)
|
|
+++ README.md (candidate)
|
|
@@ -2,213 +2,213 @@
|
|
|
|
<!-- section-id: overview -->
|
|
|
|
-Content Harness는 자연어 기반 콘텐츠 요청을 문서 계획, 정확한 기술 시각화, 유기적 이미지 생성, 검토된 publication output으로 연결하는 provider-neutral Python 시스템입니다. <!-- claim-id: C-IDENTITY -->
|
|
-
|
|
-문서 작성과 기술 도형, 유기적 이미지에는 서로 다른 생성·검토 기준이 필요합니다. 이 저장소는 세 production harness를 sibling으로 유지하고, `workflow-runtime`만 라우팅·DAG 실행·결과 전달·publication을 조정하도록 책임을 나눕니다. <!-- claim-id: C-SIBLING-MODEL -->
|
|
-
|
|
-이 README는 저장소를 처음 평가하는 개발자에게는 실행 가능한 contract chain을, 기여자에게는 capability별 변경 위치를, 리뷰어에게는 실제 생성 산출물과 현재 qualification 한계를 보여줍니다.
|
|
-
|
|
-## 책임이 섞이지 않는 네 capability
|
|
+이 저장소는 자연어로 받은 콘텐츠 요청을 문서, 기술 그림, 이미지로 만드는 파이썬 프로젝트입니다. 세 하네스가 각 결과를 만들고 `workflow-runtime`이 요청 분기, 작업 순서, 검토 결과 취합, 게시 파일 생성을 맡습니다. <!-- claim-id: C-IDENTITY -->
|
|
+
|
|
+대상 독자:
|
|
+
|
|
+- 저장소가 실제로 만드는 결과를 먼저 보고 싶은 개발자
|
|
+- 예제를 실행하거나 하네스·계약·통합 코드를 수정하려는 개발자
|
|
+
|
|
+## 검토를 마친 결과 예시
|
|
+
|
|
+<!-- section-id: showcase -->
|
|
+
|
|
+아래 세 파일은 `p6-all-harness-quality-executable-clean-architecture-20260717` 실행에서 검토와 통합 검증을 통과한 결과입니다. README에서 계속 볼 수 있도록 `docs/assets/readme-showcase/`로 옮겼습니다. <!-- claim-id: C-SHOWCASE-STATUS -->
|
|
+
|
|
+<table>
|
|
+ <tr>
|
|
+ <td width="50%" align="center">
|
|
+ <a href="docs/assets/readme-showcase/editorial-workbench.png">
|
|
+ <img src="docs/assets/readme-showcase/editorial-workbench.png" alt="햇빛이 드는 작업대에서 개발자가 건축 모형을 손으로 조정하는 장면">
|
|
+ </a>
|
|
+ <br><sub><strong>이미지 생성</strong> — 후보 세 개와 독립 검토를 거쳐 고른 에디토리얼 이미지</sub>
|
|
+ </td>
|
|
+ <td width="50%" align="center">
|
|
+ <a href="docs/assets/readme-showcase/dependency-directions.svg">
|
|
+ <img src="docs/assets/readme-showcase/dependency-directions.svg" alt="유스케이스 호출, 소스 코드 의존, 모듈 의존을 구분한 클린 아키텍처 방향 그림">
|
|
+ </a>
|
|
+ <br><sub><strong>기술 시각화</strong> — 호출 관계와 소스·모듈 의존을 구분한 SVG</sub>
|
|
+ </td>
|
|
+ </tr>
|
|
+</table>
|
|
+
|
|
+<!-- visual-id: showcase-editorial -->
|
|
+<!-- visual-id: showcase-dependency -->
|
|
+
|
|
+<p align="center">
|
|
+ <a href="docs/assets/readme-showcase/publication-preview.png">
|
|
+ <img src="docs/assets/readme-showcase/publication-preview.png" alt="에디토리얼 이미지와 의존 방향 그림을 포함한 한국어 기술 문서 전체 미리보기" width="440">
|
|
+ </a>
|
|
+ <br><sub><strong>통합 문서</strong> — 문서 작성, 이미지 생성, 기술 시각화 결과를 한 문서에 배치한 미리보기</sub>
|
|
+</p>
|
|
+
|
|
+<!-- visual-id: showcase-publication -->
|
|
+
|
|
+[산출물 출처 기록](docs/assets/readme-showcase/provenance.yaml)에는 원본 실행 경로, 파일별 SHA-256 해시, 크기, 검토 상태가 들어 있습니다. <!-- claim-id: C-SHOWCASE-PROVENANCE -->
|
|
+
|
|
+## 먼저 실행해 보기
|
|
+
|
|
+<!-- section-id: quick-start -->
|
|
+
|
|
+### 준비 사항
|
|
+
|
|
+기본 실행에는 `Python 3`, `PyYAML`, `jsonschema`가 필요합니다. `PNG` 검증과 미리보기에는 `Pillow`를 사용합니다. 기술 그림을 새로 렌더링하려면 `D2`가, `SVG`를 브라우저에서 미리 보려면 `Chrome` 또는 `Chromium`이 추가로 필요합니다. 저장소에는 이 도구들의 최소 버전이 적혀 있지 않습니다. <!-- claim-id: C-PREREQUISITES -->
|
|
+
|
|
+`pyproject.toml`, `requirements.txt` 같은 패키지 설정 파일도 없습니다. 따라서 README에서 확인되지 않은 설치 명령을 제시하지 않습니다. 필요한 도구를 준비한 뒤 저장소 루트에서 아래 명령을 실행합니다. <!-- claim-id: C-INSTALLATION-LIMIT -->
|
|
+
|
|
+### 1. 예제 요청 검사
|
|
+
|
|
+```bash
|
|
+python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
|
+```
|
|
+<!-- claim-id: C-CMD-CONTENT-JOB -->
|
|
+
|
|
+2026-07-19 실행에서는 종료 코드 0으로 끝났습니다. 출력 없이 종료되면 예제 요청이 현재 계약을 통과한 것입니다. <!-- claim-id: C-RESULT-CONTENT-JOB -->
|
|
+
|
|
+### 2. 작업 계획 확인
|
|
+
|
|
+```bash
|
|
+python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
|
|
+```
|
|
+<!-- claim-id: C-CMD-FRONT-DOOR -->
|
|
+
|
|
+2026-07-19 실행에서는 종료 코드 0과 `primary_capability: document-writing` 계획을 확인했습니다. 이 명령은 작업 계획만 만들며 외부 생성 도구를 호출하지 않습니다. <!-- claim-id: C-RESULT-FRONT-DOOR -->
|
|
+
|
|
+## 기능별 책임
|
|
|
|
<!-- section-id: capabilities -->
|
|
|
|
-### Document Writing
|
|
-
|
|
-`document-writing`은 독자·서사·근거 연결·시각화 기회를 다루고, ContentJobRequest·Content Manifest·Narrative Plan·publication draft·Visual Request를 만듭니다. 원문을 제자리에서 덮어쓰거나 renderer와 image provider를 선택하지 않습니다. <!-- claim-id: C-DOCUMENT-CAPABILITY -->
|
|
-
|
|
-### Technical Visualization
|
|
-
|
|
-`technical-visualization`은 근거에 묶인 semantic model, visual grammar, D2 렌더링, 문서·발표용 rendition을 소유합니다. 현재 실행 가능한 visual type은 `dependency-graph`와 `runtime-sequence`이며, accepted ArtifactSet에는 서로 다른 reviewer가 작성한 technical-semantic·technical-visual review가 필요합니다. <!-- claim-id: C-TECHNICAL-CAPABILITY -->
|
|
-
|
|
-### Image Generation
|
|
-
|
|
-`image-generation`은 사진·일러스트·재질·분위기 같은 organic raster를 소유합니다. production 경로는 해시된 후보 3개, pairwise comparison, 명시적 선택, 최대 한 번의 bounded repair를 사용하며, exact architecture relation·chart·state machine·긴 정확 텍스트는 이 capability의 범위 밖입니다. <!-- claim-id: C-IMAGE-CAPABILITY -->
|
|
-
|
|
-### Workflow Runtime과 Integrations
|
|
-
|
|
-`workflow-runtime`은 contract validation, routing, cycle-free DAG, freshness, retry, immutable result 수집, integration dispatch, event와 portable output publication을 소유합니다. sibling harness는 서로를 직접 호출하지 않습니다. <!-- claim-id: C-RUNTIME-CAPABILITY -->
|
|
-
|
|
-Markdown·Slides·HTML adapter는 runtime이 선택해 동결한 publication projection 하나만 소비하며, 내용·관점·route·renderer·provider를 다시 결정하지 않습니다. <!-- claim-id: C-INTEGRATIONS -->
|
|
-
|
|
-## 2분 검증
|
|
-
|
|
-<!-- section-id: quick-start -->
|
|
-
|
|
-### 전제 조건
|
|
-
|
|
-핵심 contract와 runtime은 Python 3에서 동작하며 PyYAML과 jsonschema를 사용합니다. Raster 검증·preview에는 Pillow가, technical rendering에는 D2가, SVG의 browser preview에는 Chrome 또는 Chromium이 필요합니다. 저장소는 이 도구들의 버전을 고정하지 않습니다. <!-- claim-id: C-PREREQUISITES -->
|
|
-
|
|
-현재 저장소에는 `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg`, `Pipfile`, `poetry.lock`, `uv.lock`이 없어 하나의 정본 설치 명령을 제시할 수 없습니다. 필요한 도구를 환경에 준비한 뒤 아래 검증을 실행하십시오. <!-- claim-id: C-INSTALLATION-LIMIT -->
|
|
-
|
|
-### 1. 자연어 요청의 contract 확인
|
|
-
|
|
-```bash
|
|
-python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
|
-```
|
|
-<!-- claim-id: C-CMD-CONTENT-JOB -->
|
|
-
|
|
-이 명령은 이번 README 작성 세션에서 exit code 0으로 완료됐습니다. 출력 없이 종료되면 체크인된 ContentJobRequest가 현재 contract를 통과한 것입니다. <!-- claim-id: C-RESULT-CONTENT-JOB -->
|
|
-
|
|
-### 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 .
|
|
-```
|
|
-<!-- claim-id: C-CMD-FRONT-DOOR -->
|
|
-
|
|
-이 명령도 exit code 0으로 완료됐고 `primary_capability: document-writing`인 plan을 출력했습니다. 이는 계획 단계의 확인이며 author·review provider를 호출하는 production 실행은 아닙니다. <!-- claim-id: C-RESULT-FRONT-DOOR -->
|
|
-
|
|
-## 요청에서 publication까지
|
|
+### 문서 작성 — `document-writing`
|
|
+
|
|
+독자, 글의 순서, 근거 연결, 그림이 필요한 위치를 정합니다. 요청 명세, 내용 명세, 서사 계획, 게시 초안, 그림 요청을 만들지만 원문을 덮어쓰거나 렌더러를 고르지는 않습니다. <!-- claim-id: C-DOCUMENT-CAPABILITY -->
|
|
+
|
|
+### 기술 시각화 — `technical-visualization`
|
|
+
|
|
+코드와 문서에서 확인한 관계를 의미 모형으로 만들고 D2로 렌더링합니다. 현재 `dependency-graph`와 `runtime-sequence`를 만들 수 있습니다. 기술 내용과 화면 표현을 서로 다른 검토자가 승인해야 산출물 묶음이 `accepted`가 됩니다. <!-- claim-id: C-TECHNICAL-CAPABILITY -->
|
|
+
|
|
+### 이미지 생성 — `image-generation`
|
|
+
|
|
+사진, 일러스트, 재질, 분위기처럼 유기적인 래스터 이미지를 만듭니다. 후보 세 개를 비교해 하나를 고르고, 필요한 경우 한 번만 부분 수정합니다. 정확한 아키텍처 관계, 차트, 상태 전이, 긴 본문은 이 기능으로 만들지 않습니다. <!-- claim-id: C-IMAGE-CAPABILITY -->
|
|
+
|
|
+### 작업 실행과 게시 — `workflow-runtime`, `integrations`
|
|
+
|
|
+`workflow-runtime`은 요청 검사, 분기, 작업 순서, 재시도, 결과 취합을 담당합니다. 세 하네스는 서로를 직접 호출하지 않습니다. <!-- claim-id: C-RUNTIME-CAPABILITY -->
|
|
+
|
|
+`Markdown`, `Slides`, `HTML` 어댑터는 작업 실행기가 확정한 게시 자료만 받습니다. 어댑터가 내용이나 생성 도구를 다시 고르지는 않습니다. <!-- claim-id: C-INTEGRATIONS -->
|
|
+
|
|
+## 요청이 결과가 되는 과정
|
|
|
|
<!-- section-id: execution-model -->
|
|
|
|
-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만으로 표현하기 어려운 조건을 확인합니다. <!-- claim-id: C-CONTRACT-CHAIN -->
|
|
-
|
|
-Visual Request의 신호가 technical-only이면 `technical-visualization`, image-only이면 `image-generation`, 둘 다이면 runtime-owned hybrid DAG로 라우팅됩니다. 신호가 없으면 `BLOCKED_UNRESOLVED`, 명시적 충돌이면 `ROUTING_CONFLICT`입니다. <!-- claim-id: C-ROUTING -->
|
|
-
|
|
-각 harness는 plan 또는 immutable JobResult를 runtime에 반환합니다. Runtime만 sibling 결과를 조립하고 accepted rendition의 publication projection을 동결해 integration adapter로 넘깁니다. <!-- claim-id: C-RUNTIME-OWNERSHIP -->
|
|
-
|
|
-Deterministic validation은 expert review를 대신하지 않습니다. 필수 review가 없는 유효한 technical 결과는 `produced`에 머물며 `accepted`나 integration-ready로 승격되지 않습니다. <!-- claim-id: C-ACCEPTANCE-BOUNDARY -->
|
|
-
|
|
-다음 흐름은 request와 contract가 runtime에서 sibling capability로 분기한 뒤 reviewed draft 또는 accepted ArtifactSet으로 합류하는 지점을 요약합니다. <!-- claim-id: C-FLOW-VISUAL -->
|
|
+파일 계약은 `ContentJobRequest` → `Content Manifest` → `Narrative Plan` → `Visual Request` → `ArtifactSet` → 게시 자료 순서로 이어집니다. 각 단계는 다음 단계가 받아도 되는 정보와 검토 상태를 제한합니다. <!-- claim-id: C-CONTRACT-CHAIN -->
|
|
+
|
|
+그림 요청이 기술 관계만 포함하면 `technical-visualization`, 이미지 표현만 포함하면 `image-generation`으로 보냅니다. 둘 다 필요하면 `workflow-runtime`이 두 결과를 합치는 작업 순서를 만듭니다. 신호가 없거나 서로 충돌하면 실행을 막습니다. <!-- claim-id: C-ROUTING -->
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
- A["자연어 요청"] --> B["ContentJobRequest / Visual Request"]
|
|
- B --> R{"workflow-runtime<br/>routing · DAG · freshness"}
|
|
- R --> D["document-writing"]
|
|
- R --> T["technical-visualization"]
|
|
- R --> I["image-generation"]
|
|
- T --> H["runtime-owned<br/>hybrid composition"]
|
|
+ A["자연어 요청"] --> B["요청 명세"]
|
|
+ B --> R{"workflow-runtime<br/>분기 · 작업 순서 · 검토"}
|
|
+ R --> D["document-writing<br/>문서 초안"]
|
|
+ R --> T["technical-visualization<br/>기술 그림"]
|
|
+ R --> I["image-generation<br/>이미지"]
|
|
+ T --> H["혼합 합성"]
|
|
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"]
|
|
+ D --> P["검토된 게시 자료"]
|
|
+ T --> P
|
|
+ I --> P
|
|
+ H --> P
|
|
+ P --> O["Markdown · Slides · HTML"]
|
|
```
|
|
|
|
<!-- visual-id: content-flow -->
|
|
|
|
-## 생성 산출물 둘러보기
|
|
-
|
|
-<!-- section-id: artifacts -->
|
|
-
|
|
-### 버전 관리되는 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입니다. <!-- claim-id: C-VERSIONED-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가 있습니다. <!-- claim-id: C-LOCAL-P6-OUTPUT -->
|
|
-
|
|
-문서와 기술 시각화를 함께 시험한 `runs/docvis-20260716-executable-clean-architecture-part1/`에는 통합 HTML, desktop·mobile 문서 preview, 두 figure의 target별 SVG와 PNG fallback, delivery·asset manifest가 있습니다. <!-- claim-id: C-LOCAL-DOCVIS-OUTPUT -->
|
|
-
|
|
-Best-of-three 이미지 예제인 `runs/img-20260716-japanese-animation-test/`는 3개 후보 중 attempt 2를 `BEST_OF_N_PASS`로 선택하고 `outputs/final-selected.png`를 남겼습니다. <!-- claim-id: C-LOCAL-IMAGE-OUTPUT -->
|
|
-
|
|
-| 산출물 유형 | 로컬 예시 | 확인할 것 |
|
|
+`workflow-runtime`이 세 하네스로 요청을 나누고, 검토를 마친 결과를 게시 자료로 합칩니다. <!-- claim-id: C-FLOW-RELATIONSHIPS -->
|
|
+
|
|
+구조 검사만 통과한 결과는 바로 게시하지 않습니다. 문서는 지정된 검토를 마쳐야 하고, 기술 그림과 이미지는 `accepted`이면서 통합 준비 상태여야 합니다. <!-- claim-id: C-ACCEPTANCE-BOUNDARY -->
|
|
+
|
|
+## 저장소 구성과 변경 위치
|
|
+
|
|
+<!-- section-id: architecture -->
|
|
+
|
|
+| 경로 | 맡는 일 | 이럴 때 먼저 확인 |
|
|
| --- | --- | --- |
|
|
-| 생성 문서 | `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/<purpose>/run-<YYYYMMDDTHHMMSSZ>-NNN/`을 할당하고, reviewed deliverable이 있으면 `<run-root>/output/index.html`과 hash-bound `manifest.yaml`을 만들 수 있습니다. <!-- claim-id: C-RUNS-POLICY -->
|
|
-
|
|
-따라서 위 로컬 PNG·SVG를 README에 직접 임베드하지 않았습니다. GitHub에서 지속되는 gallery가 필요하면 검토된 파일을 `examples/` 또는 별도 versioned 문서 asset 경로로 승격하고, provenance와 manifest를 함께 갱신해야 합니다. <!-- claim-id: C-ASSET-PROMOTION -->
|
|
-
|
|
-자세한 실행 데이터 정책은 [Runtime workspace](runs/README.md)를 참고하십시오.
|
|
-
|
|
-## 저장소 구조와 변경 위치
|
|
-
|
|
-<!-- section-id: architecture -->
|
|
-
|
|
-| 경로 | 정본 책임 | 변경할 때 함께 볼 곳 |
|
|
-| --- | --- | --- |
|
|
-| `.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을 담당합니다. <!-- claim-id: C-LAYER-OWNERSHIP -->
|
|
-
|
|
-정본 의존 방향은 adapter → harnesses → packages이며, `workflow-runtime`은 handler registry를 통해 harness를 실행하고 frozen projection만 integrations로 보냅니다. Contract와 integration adapter가 harness implementation을 역으로 소유하지 않습니다. <!-- claim-id: C-DEPENDENCY-DIRECTION -->
|
|
-
|
|
-구체적인 contract chain과 hybrid composition 경계는 [ARCHITECTURE.md](ARCHITECTURE.md)에 있습니다.
|
|
-
|
|
-## 검증 명령과 증거 수준
|
|
+| `.agents/`, `.codex/` | 도구가 하네스를 찾게 하는 얇은 연결부 | 도구별 진입점 변경 |
|
|
+| `harnesses/` | 문서·기술 그림·이미지 생성 정책과 구현 | 생성 방식이나 검토 규칙 변경 |
|
|
+| `packages/` | 파일 계약, 공통 검사, 작업 실행기 | 명세 구조나 실행 순서 변경 |
|
|
+| `integrations/` | 확정된 게시 자료를 `Markdown`·`Slides`·`HTML`로 변환 | 출력 형식 변경 |
|
|
+| `tests/` | 계약·실행·실패 조건·저장소 구성 검사 | 동작 변경과 회귀 검사 추가 |
|
|
+| `examples/` | 버전 관리되는 실행 예제 | 재현 가능한 예제 추가 |
|
|
+| `benchmarks/` | 평가 자료와 판정 결과 | 품질 기준이나 비교 자료 변경 |
|
|
+| `runs/` | 버전 관리하지 않는 실행 기록 | 실행 재개와 실패 원인 확인 |
|
|
+
|
|
+정본 의존 방향은 도구 연결부 → 하네스 → 공통 계약입니다. `workflow-runtime`은 등록 파일을 통해 하네스를 실행하고, 확정된 게시 자료만 `integrations`로 보냅니다. <!-- claim-id: C-DEPENDENCY-DIRECTION -->
|
|
+
|
|
+전체 계약 사슬과 혼합 합성 경계는 [ARCHITECTURE.md](ARCHITECTURE.md)에 정리돼 있습니다.
|
|
+
|
|
+## 검증
|
|
|
|
<!-- section-id: verification -->
|
|
|
|
-이번 README 작업에서는 다음 세 검증도 저장소 루트에서 실제 실행했습니다.
|
|
+아래 결과는 2026-07-19에 저장소 루트에서 확인했습니다. <!-- claim-id: C-VERIFICATION-DATE -->
|
|
+
|
|
+### 내용 명세
|
|
|
|
```bash
|
|
python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
|
|
```
|
|
<!-- claim-id: C-CMD-CONTENT-MANIFEST -->
|
|
|
|
-결과: `VALID`, exit code 0. <!-- claim-id: C-RESULT-CONTENT-MANIFEST -->
|
|
+결과는 `VALID`, 종료 코드 0입니다. <!-- claim-id: C-RESULT-CONTENT-MANIFEST -->
|
|
+
|
|
+### 기술 그림 산출물 묶음
|
|
|
|
```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
|
|
```
|
|
<!-- claim-id: C-CMD-ARTIFACT-SET -->
|
|
|
|
-결과: `VALID`, exit code 0. 이 검증은 체크인된 contract fixture를 대상으로 하며 fresh renderer execution을 대신하지 않습니다. <!-- claim-id: C-RESULT-ARTIFACT-SET -->
|
|
+결과는 `VALID`, 종료 코드 0입니다. 이 명령은 버전 관리되는 계약 예시를 검사하며 새 그림을 렌더링하지 않습니다. <!-- claim-id: C-RESULT-ARTIFACT-SET -->
|
|
+
|
|
+### 저장소 구성
|
|
|
|
```bash
|
|
python3 -m unittest tests.conformance.test_repository_layout
|
|
```
|
|
<!-- claim-id: C-CMD-LAYOUT-TEST -->
|
|
|
|
-결과: 18개 test가 통과했습니다. 이 범위는 canonical directory와 adapter boundary를 확인하며 전체 suite를 대신하지 않습니다. <!-- claim-id: C-RESULT-LAYOUT-TEST -->
|
|
-
|
|
-전체 discovery 명령은 다음과 같이 정의돼 있습니다.
|
|
+구성 검사 18개가 통과했습니다. <!-- claim-id: C-RESULT-LAYOUT-TEST -->
|
|
+
|
|
+### 전체 테스트
|
|
|
|
```bash
|
|
python3 -m unittest discover -s tests -p 'test_*.py'
|
|
```
|
|
<!-- claim-id: C-CMD-FULL-SUITE -->
|
|
|
|
-전체 suite는 이번 README 작업에서 재실행하지 않았습니다. [2026-07-18 refactoring review](docs/refactoring-review.md#verification-performed)는 별도의 300-test pass를 기록하지만, 이를 이번 실행 결과로 재표현하지 않습니다. <!-- claim-id: C-FULL-SUITE-SCOPE -->
|
|
-
|
|
-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)에 분리돼 있습니다. <!-- claim-id: C-E2E-PREREQUISITES -->
|
|
-
|
|
-## 현재 상태와 한계
|
|
+전체 테스트 300개가 615.249초에 통과했습니다. 외부 자료와 별도 검토 파일을 넣어야 하는 종단 간 작업은 이 결과와 구분해야 합니다. <!-- claim-id: C-RESULT-FULL-SUITE -->
|
|
+
|
|
+외부 입력을 준비하는 방법은 [종단 간 작업 안내](tests/end-to-end/README.md)에 있습니다. <!-- claim-id: C-E2E-PREREQUISITES -->
|
|
+
|
|
+## 현재 한계
|
|
|
|
<!-- section-id: limitations -->
|
|
|
|
-- **설치 재현성:** dependency packaging manifest와 version pin이 없으므로 README는 임의의 패키지 설치 명령이나 최소 버전을 만들지 않습니다. <!-- claim-id: C-LIMIT-PACKAGING -->
|
|
-- **산출물 지속성:** 실제 PNG·SVG·HTML·Markdown 샘플은 로컬 `runs/`에 있지만 clean checkout이나 GitHub 링크의 영속성을 보장하지 않습니다. <!-- claim-id: C-LIMIT-RUNS -->
|
|
-- **Benchmark 성숙도:** document-writing과 image-generation suite는 corpus만 정의되고 결과가 pending입니다. Technical visualization의 dependency-direction 비교도 일부 condition과 human preference가 남아 있습니다. <!-- claim-id: C-LIMIT-BENCHMARKS -->
|
|
-- **Hybrid qualification:** `d2-svg-layer-compositor`의 자동 16-case 증거는 PASS지만 human Gate 3는 `PENDING`입니다. 이 renderer는 qualification candidate이며 qualified renderer로 소개하면 안 됩니다. <!-- claim-id: C-LIMIT-HYBRID -->
|
|
-- **E2E 입력:** 전체 품질·dependency-direction·redraw 경로는 이 저장소만으로 완결되지 않고 외부 evidence/source와 완료된 expert review를 요구합니다. <!-- claim-id: C-LIMIT-E2E -->
|
|
-
|
|
-## 문서와 정본 지도
|
|
+- **설치 절차:** 패키지 설정 파일과 버전 고정값이 없어 하나의 재현 가능한 설치 명령을 제공하지 못합니다. <!-- claim-id: C-LIMIT-PACKAGING -->
|
|
+- **실행 기록:** `runs/`는 버전 관리 대상이 아닙니다. 재사용할 예시는 `docs/`나 `examples/`로 옮기고 출처를 함께 기록해야 합니다. <!-- claim-id: C-LIMIT-RUNS -->
|
|
+- **외부 입력:** 일부 종단 간 작업에는 외부 Java·Gradle 저장소, 원문, 완료된 전문가 검토 파일이 필요합니다. <!-- claim-id: C-LIMIT-E2E -->
|
|
+- **평가 자료:** 문서 작성과 이미지 생성 평가는 자료 구조만 정의돼 있고 결과는 아직 없습니다. 기술 시각화 비교에도 실행하지 않은 조건과 사람 선호 판정이 남아 있습니다. <!-- claim-id: C-LIMIT-BENCHMARKS -->
|
|
+- **혼합 합성:** `d2-svg-layer-compositor`는 자동 검사에 통과했지만 사람 검토가 남아 있어 정식 렌더러로 분류하지 않습니다. <!-- claim-id: C-LIMIT-HYBRID -->
|
|
+
|
|
+## 더 읽을 문서
|
|
|
|
<!-- section-id: documentation -->
|
|
|
|
-정본 설계는 `ARCHITECTURE.md`, 문서 색인은 `docs/README.md`, 실행 작업공간 정책은 `runs/README.md`에 있습니다. <!-- claim-id: C-DOCUMENTATION-MAP -->
|
|
-
|
|
-- [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를 함께 갱신하십시오.
|
|
+- [전체 설계](ARCHITECTURE.md) — 계층, 계약, 분기, 검토 권한
|
|
+- [문서 색인](docs/README.md) — 현재 문서와 구현 이력의 구분
|
|
+- [실행 작업공간](runs/README.md) — 새 실행 할당, 재개, 결과 게시
|
|
+- [문서 작성 하네스](harnesses/document-writing/README.md)
|
|
+- [기술 시각화 하네스](harnesses/technical-visualization/README.md)
|
|
+- [이미지 생성 하네스](harnesses/image-generation/README.md)
|
|
+- [작업 실행기](packages/workflow-runtime/README.md)
|
|
+- [Clean Architecture 예제](examples/clean-architecture/)
|
|
+- [평가 자료](benchmarks/technical-visualization/README.md) · [이미지 품질](benchmarks/image-quality/README.md) · [혼합 합성](benchmarks/hybrid-composition/README.md)
|