init: readme 작성 하네스 설계
This commit is contained in:
DongHyeonka
@@ -0,0 +1,214 @@
|
||||
# Content Harness
|
||||
|
||||
<!-- 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
|
||||
|
||||
<!-- 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까지
|
||||
|
||||
<!-- 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 -->
|
||||
|
||||
```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"]
|
||||
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"]
|
||||
```
|
||||
|
||||
<!-- 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 -->
|
||||
|
||||
| 산출물 유형 | 로컬 예시 | 확인할 것 |
|
||||
| --- | --- | --- |
|
||||
| 생성 문서 | `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)에 있습니다.
|
||||
|
||||
## 검증 명령과 증거 수준
|
||||
|
||||
<!-- section-id: verification -->
|
||||
|
||||
이번 README 작업에서는 다음 세 검증도 저장소 루트에서 실제 실행했습니다.
|
||||
|
||||
```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 -->
|
||||
|
||||
```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 -->
|
||||
|
||||
```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 명령은 다음과 같이 정의돼 있습니다.
|
||||
|
||||
```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 -->
|
||||
|
||||
## 현재 상태와 한계
|
||||
|
||||
<!-- 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 -->
|
||||
|
||||
## 문서와 정본 지도
|
||||
|
||||
<!-- 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를 함께 갱신하십시오.
|
||||
@@ -0,0 +1,214 @@
|
||||
# Content Harness
|
||||
|
||||
<!-- 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
|
||||
|
||||
<!-- 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까지
|
||||
|
||||
<!-- 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 -->
|
||||
|
||||
```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"]
|
||||
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"]
|
||||
```
|
||||
|
||||
<!-- 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 -->
|
||||
|
||||
| 산출물 유형 | 로컬 예시 | 확인할 것 |
|
||||
| --- | --- | --- |
|
||||
| 생성 문서 | `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)에 있습니다.
|
||||
|
||||
## 검증 명령과 증거 수준
|
||||
|
||||
<!-- section-id: verification -->
|
||||
|
||||
이번 README 작업에서는 다음 세 검증도 저장소 루트에서 실제 실행했습니다.
|
||||
|
||||
```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 -->
|
||||
|
||||
```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 -->
|
||||
|
||||
```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 명령은 다음과 같이 정의돼 있습니다.
|
||||
|
||||
```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 -->
|
||||
|
||||
## 현재 상태와 한계
|
||||
|
||||
<!-- 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 -->
|
||||
|
||||
## 문서와 정본 지도
|
||||
|
||||
<!-- 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를 함께 갱신하십시오.
|
||||
@@ -0,0 +1,364 @@
|
||||
--- README.md (current)
|
||||
+++ README.md (candidate)
|
||||
@@ -1,153 +1,214 @@
|
||||
# Content Harness
|
||||
|
||||
-A provider-neutral system for planning technical documents, producing exact
|
||||
-technical visuals, generating organic imagery, and integrating accepted assets
|
||||
-without coupling sibling capabilities.
|
||||
-
|
||||
-Natural-language requests enter through `ContentJobRequest`; users are not
|
||||
-expected to author the YAML. The document-writing intake normalizes conversation
|
||||
-plus IDE/provider context, after which workflow-runtime plans the job or routes
|
||||
-later Visual Requests.
|
||||
-
|
||||
-The canonical design is documented in [ARCHITECTURE.md](ARCHITECTURE.md), with
|
||||
-a task-oriented index in [docs/README.md](docs/README.md). AI tools enter
|
||||
-through thin skills under `.agents/`; implementation and policy live under
|
||||
-`packages/`, `harnesses/`, and `integrations/`. Earlier delivery phases are
|
||||
-kept only as [implementation history](docs/README.md#implementation-history).
|
||||
-The latest ownership and lifecycle audit is the
|
||||
-[repository refactoring review](docs/refactoring-review.md).
|
||||
-
|
||||
-Current execution additionally enforces current-file freshness at execution
|
||||
-and integration, content-addressed validation receipts, independent scoped
|
||||
-reviews, exact per-target technical semantics, and best-of-three raster
|
||||
-candidate selection. Missing expert review remains an honest `produced` state;
|
||||
-it is never promoted to `accepted` by deterministic checks alone.
|
||||
-
|
||||
-## Capabilities
|
||||
-
|
||||
-- `document-writing`: narrative profiles and plans, evidence bindings,
|
||||
- repetition and abstraction control, natural technical prose, and visual
|
||||
- request emission.
|
||||
-- `technical-visualization`: grounded semantic models, exact technical grammar,
|
||||
- deterministic renderers, document/presentation/reveal variants, and semantic
|
||||
- plus visual review.
|
||||
-- `image-generation`: photography, illustration, organic raster editing,
|
||||
- art-directed candidate search, independent review, and bounded local repair.
|
||||
-- `workflow-runtime`: contract validation, freshness, routing, DAG execution,
|
||||
- immutable result collection, rollback dispatch, events, integration, and
|
||||
- automatic portable `<run-root>/output/` publication for reviewed results.
|
||||
-
|
||||
-## Execution model
|
||||
-
|
||||
-Every intake or production invocation that passes its pre-execution contract
|
||||
-and freshness checks starts a new immutable run. Invalid or stale input fails
|
||||
-before allocation. The runtime does not scan `runs/` for a similar request,
|
||||
-borrow prior artifacts, or infer resume from a matching request or workflow ID.
|
||||
-It allocates:
|
||||
-
|
||||
-```text
|
||||
-runs/<purpose>/run-<YYYYMMDDTHHMMSSZ>-NNN/run.yaml
|
||||
-```
|
||||
-
|
||||
-`<purpose>` is a stable, lower-case kebab-case description of the intended
|
||||
-outcome. The timestamp is UTC; `NNN` resolves same-second collisions. The
|
||||
-request ID identifies the content intent, the workflow ID identifies its
|
||||
-planned DAG, and the run ID identifies one concrete execution. They are never
|
||||
-interchangeable.
|
||||
-
|
||||
-Resume is an explicit recovery operation only. The user must name the exact
|
||||
-failed run; the runtime validates its frozen inputs and appends a
|
||||
-`WORKFLOW_RESUMED` event without changing immutable `run.yaml`. Completed,
|
||||
-stale, or merely similar runs are never resume candidates. See the full
|
||||
-[runtime workspace policy](runs/README.md).
|
||||
-
|
||||
-## Repository organization
|
||||
-
|
||||
-- `packages/`: contracts, shared validation, reference registry, export
|
||||
- validation, and workflow runtime.
|
||||
-- `harnesses/`: capability-owned policies, profiles, workflows, validators,
|
||||
- reviewers, and implementation.
|
||||
-- `integrations/`: publication-only Markdown, Slides, and HTML adapters.
|
||||
-- `examples/`: versioned executable examples.
|
||||
-- `tests/`: conformance, regression, failure-injection, and golden artifacts.
|
||||
-- `benchmarks/`: evaluation suites, results, and failure corpora.
|
||||
-- `runs/`: ignored local executions; never a canonical source.
|
||||
-- `docs/`: documentation index and clearly separated implementation history.
|
||||
-
|
||||
-Directories are created when a capability has content to own or when a run
|
||||
-actually reaches that stage. Empty placeholder trees are intentionally avoided;
|
||||
-optional run subdirectories may therefore be absent.
|
||||
-
|
||||
-Canonical capability directories keep their hyphenated IDs on disk. Stable
|
||||
-Python imports use only thin underscore namespace adapters under `packages/`;
|
||||
-there is no second implementation tree under `harnesses/`.
|
||||
-
|
||||
-## Quick validation
|
||||
-
|
||||
-The checked-in Clean Architecture example forms one executable contract chain.
|
||||
-
|
||||
-```bash
|
||||
-python3 -m packages.content_job_contract.validate_content_job \
|
||||
- examples/clean-architecture/content-job-request.yaml --repo-root .
|
||||
-
|
||||
-python3 -m packages.workflow_runtime.content_runtime front-door \
|
||||
- --workflow-request \
|
||||
- examples/clean-architecture/workflow-request.content-job.yaml \
|
||||
- --repo-root .
|
||||
-```
|
||||
-
|
||||
-```bash
|
||||
-python3 -m packages.content_contract.validate_content \
|
||||
- examples/clean-architecture/content-manifest.yaml --repo-root .
|
||||
-
|
||||
-python3 -m packages.content_contract.validate_narrative_plan \
|
||||
- examples/clean-architecture/narrative-plan.yaml \
|
||||
- --content-manifest examples/clean-architecture/content-manifest.yaml \
|
||||
- --reference-registry examples/clean-architecture/reference-registry.yaml \
|
||||
- --publication examples/clean-architecture/source.md
|
||||
-
|
||||
-python3 -m packages.visual_request_contract.validate_visual_request \
|
||||
- examples/clean-architecture/visual-request.yaml --repo-root . \
|
||||
- --content-manifest examples/clean-architecture/content-manifest.yaml \
|
||||
- --reference-registry examples/clean-architecture/reference-registry.yaml
|
||||
-
|
||||
-python3 -m packages.artifact_contract.validate_artifact_set \
|
||||
- examples/clean-architecture/artifact/attempt-01/artifact-set.yaml \
|
||||
- --request examples/clean-architecture/visual-request.yaml
|
||||
-
|
||||
-python3 -m packages.workflow_runtime.content_runtime plan \
|
||||
- --request examples/clean-architecture/visual-request.yaml \
|
||||
- --content-manifest examples/clean-architecture/content-manifest.yaml \
|
||||
- --reference-registry examples/clean-architecture/reference-registry.yaml \
|
||||
- --repo-root .
|
||||
-```
|
||||
-
|
||||
-Fresh execution asks the allocator for a purpose-scoped run:
|
||||
-
|
||||
-```bash
|
||||
-python3 -m packages.workflow_runtime.content_runtime execute \
|
||||
- --request examples/clean-architecture/visual-request.yaml \
|
||||
- --content-manifest examples/clean-architecture/content-manifest.yaml \
|
||||
- --reference-registry examples/clean-architecture/reference-registry.yaml \
|
||||
- --repo-root . \
|
||||
- --runs-dir runs \
|
||||
- --purpose render-clean-architecture-dependencies
|
||||
-```
|
||||
-
|
||||
-For intake and explicit recovery commands, follow the runtime package
|
||||
-[usage guide](packages/workflow-runtime/README.md); do not copy a local run path
|
||||
-from documentation or a previous session.
|
||||
-
|
||||
-Image-generation implementation and templates are under
|
||||
-`harnesses/image-generation/`; technical-visual contracts, templates, and
|
||||
-validators are under `harnesses/technical-visualization/`.
|
||||
-
|
||||
-## Tests
|
||||
+<!-- 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
|
||||
+
|
||||
+<!-- 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까지
|
||||
+
|
||||
+<!-- 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 -->
|
||||
+
|
||||
+```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"]
|
||||
+ 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"]
|
||||
+```
|
||||
+
|
||||
+<!-- 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 -->
|
||||
+
|
||||
+| 산출물 유형 | 로컬 예시 | 확인할 것 |
|
||||
+| --- | --- | --- |
|
||||
+| 생성 문서 | `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)에 있습니다.
|
||||
+
|
||||
+## 검증 명령과 증거 수준
|
||||
+
|
||||
+<!-- section-id: verification -->
|
||||
+
|
||||
+이번 README 작업에서는 다음 세 검증도 저장소 루트에서 실제 실행했습니다.
|
||||
+
|
||||
+```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 -->
|
||||
+
|
||||
+```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 -->
|
||||
+
|
||||
+```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 명령은 다음과 같이 정의돼 있습니다.
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
```
|
||||
-
|
||||
-Python helpers require Python 3, PyYAML, jsonschema, and Pillow. Supported
|
||||
-technical rendering requires D2. SVG preview rendering uses a local Chrome or
|
||||
-Chromium executable.
|
||||
+<!-- 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 -->
|
||||
+
|
||||
+## 현재 상태와 한계
|
||||
+
|
||||
+<!-- 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 -->
|
||||
+
|
||||
+## 문서와 정본 지도
|
||||
+
|
||||
+<!-- 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를 함께 갱신하십시오.
|
||||
@@ -0,0 +1,7 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
target-rel: README.md
|
||||
generated-hash: sha256:bb63802996c738e926449e65ee9319825b4bf4f2ab3379ee31afa85e1d5c3cc4
|
||||
target-before-hash: sha256:85b08ed1275078bd6ab2a3b72f591658c16ac17e3d3b9f9d9d902542dd119b50
|
||||
repository-snapshot-hash: sha256:d65d7446cad11d46dabd2080c8393059f36fab426f4d62f18183b2c144c3de29
|
||||
review-score: 94
|
||||
@@ -0,0 +1,288 @@
|
||||
schema-version: 1
|
||||
claims:
|
||||
- id: C-IDENTITY
|
||||
type: factual
|
||||
statement: Content Harness는 자연어 기반 콘텐츠 요청을 문서 계획, 정확한 기술 시각화, 유기적 이미지 생성, 검토된 publication output으로 연결하는 provider-neutral Python 시스템입니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-IDENTITY}, {fact-id: F-CONTRACT-CHAIN}, {fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-SIBLING-MODEL
|
||||
type: factual
|
||||
statement: 이 저장소는 세 production harness를 sibling으로 유지하고, `workflow-runtime`만 라우팅·DAG 실행·결과 전달·publication을 조정하도록 책임을 나눕니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-SIBLING-HARNESSES}, {fact-id: F-ROUTING}]
|
||||
status: supported
|
||||
|
||||
- id: C-DOCUMENT-CAPABILITY
|
||||
type: factual
|
||||
statement: "`document-writing`은 독자·서사·근거 연결·시각화 기회를 다루고, ContentJobRequest·Content Manifest·Narrative Plan·publication draft·Visual Request를 만듭니다."
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-CAPABILITY-DOCUMENT}]
|
||||
status: supported
|
||||
|
||||
- id: C-TECHNICAL-CAPABILITY
|
||||
type: factual
|
||||
statement: "`technical-visualization`은 근거에 묶인 semantic model, visual grammar, D2 렌더링, 문서·발표용 rendition을 소유합니다."
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-CAPABILITY-TECHNICAL}]
|
||||
status: supported
|
||||
|
||||
- id: C-IMAGE-CAPABILITY
|
||||
type: factual
|
||||
statement: "`image-generation`은 사진·일러스트·재질·분위기 같은 organic raster를 소유합니다."
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-CAPABILITY-IMAGE}]
|
||||
status: supported
|
||||
|
||||
- id: C-RUNTIME-CAPABILITY
|
||||
type: factual
|
||||
statement: "`workflow-runtime`은 contract validation, routing, cycle-free DAG, freshness, retry, immutable result 수집, integration dispatch, event와 portable output publication을 소유합니다."
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-SIBLING-HARNESSES}, {fact-id: F-RUN-WORKSPACE}, {fact-id: F-PORTABLE-OUTPUT}]
|
||||
status: supported
|
||||
|
||||
- id: C-INTEGRATIONS
|
||||
type: factual
|
||||
statement: Markdown·Slides·HTML adapter는 runtime이 선택해 동결한 publication projection 하나만 소비하며, 내용·관점·route·renderer·provider를 다시 결정하지 않습니다.
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-PREREQUISITES
|
||||
type: factual
|
||||
statement: 핵심 contract와 runtime은 Python 3에서 동작하며 PyYAML과 jsonschema를 사용합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-PREREQUISITES}]
|
||||
status: supported
|
||||
|
||||
- id: C-INSTALLATION-LIMIT
|
||||
type: factual
|
||||
statement: 현재 저장소에는 `pyproject.toml`, `requirements.txt`, `setup.py`, `setup.cfg`, `Pipfile`, `poetry.lock`, `uv.lock`이 없어 하나의 정본 설치 명령을 제시할 수 없습니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-NO-PACKAGE-MANIFEST}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-CONTENT-JOB
|
||||
type: factual
|
||||
statement: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXAMPLE-CHAIN}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-CONTENT-JOB
|
||||
type: factual
|
||||
statement: 이 명령은 이번 README 작성 세션에서 exit code 0으로 완료됐습니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-FRONT-DOOR
|
||||
type: factual
|
||||
statement: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXAMPLE-CHAIN}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-FRONT-DOOR
|
||||
type: factual
|
||||
statement: "이 명령도 exit code 0으로 완료됐고 `primary_capability: document-writing`인 plan을 출력했습니다."
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CONTRACT-CHAIN
|
||||
type: factual
|
||||
statement: Contract chain은 `ContentJobRequest` → `Content Manifest` → `Narrative Plan` → `Visual Request` → `ArtifactSet` → frozen publication projection 순서로 책임을 좁혀 갑니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-CONTRACT-CHAIN}]
|
||||
status: supported
|
||||
|
||||
- id: C-ROUTING
|
||||
type: factual
|
||||
statement: Visual Request의 신호가 technical-only이면 `technical-visualization`, image-only이면 `image-generation`, 둘 다이면 runtime-owned hybrid DAG로 라우팅됩니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-ROUTING}]
|
||||
status: supported
|
||||
|
||||
- id: C-RUNTIME-OWNERSHIP
|
||||
type: factual
|
||||
statement: 각 harness는 plan 또는 immutable JobResult를 runtime에 반환합니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-SIBLING-HARNESSES}, {fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-ACCEPTANCE-BOUNDARY
|
||||
type: factual
|
||||
statement: 필수 review가 없는 유효한 technical 결과는 `produced`에 머물며 `accepted`나 integration-ready로 승격되지 않습니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-CAPABILITY-TECHNICAL}]
|
||||
status: supported
|
||||
|
||||
- id: C-FLOW-VISUAL
|
||||
type: factual
|
||||
statement: 다음 흐름은 request와 contract가 runtime에서 sibling capability로 분기한 뒤 reviewed draft 또는 accepted ArtifactSet으로 합류하는 지점을 요약합니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-SIBLING-HARNESSES}, {fact-id: F-CONTRACT-CHAIN}, {fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-VERSIONED-FIXTURE
|
||||
type: factual
|
||||
statement: "`artifact/attempt-01/`에는 document·presentation·reveal-step SVG와 `accepted`/`ready` 상태의 manifest가 있지만, 이는 renderer-backed golden이 아니라 최소 contract fixture입니다."
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-VERSIONED-VISUALS}]
|
||||
status: supported
|
||||
|
||||
- id: C-LOCAL-P6-OUTPUT
|
||||
type: factual
|
||||
statement: "`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가 있습니다."
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-LOCAL-CROSS-HARNESS-OUTPUT}]
|
||||
status: supported
|
||||
|
||||
- id: C-LOCAL-DOCVIS-OUTPUT
|
||||
type: factual
|
||||
statement: 문서와 기술 시각화를 함께 시험한 `runs/docvis-20260716-executable-clean-architecture-part1/`에는 통합 HTML, desktop·mobile 문서 preview, 두 figure의 target별 SVG와 PNG fallback, delivery·asset manifest가 있습니다.
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-LOCAL-DOCUMENT-VISUALIZATION}]
|
||||
status: supported
|
||||
|
||||
- id: C-LOCAL-IMAGE-OUTPUT
|
||||
type: factual
|
||||
statement: Best-of-three 이미지 예제인 `runs/img-20260716-japanese-animation-test/`는 3개 후보 중 attempt 2를 `BEST_OF_N_PASS`로 선택하고 `outputs/final-selected.png`를 남겼습니다.
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-LOCAL-IMAGE-OUTPUT}]
|
||||
status: supported
|
||||
|
||||
- id: C-RUNS-POLICY
|
||||
type: factual
|
||||
statement: "`runs/**`는 `.gitignore` 대상인 로컬 immutable 실행 작업공간이며 cache나 source of truth가 아닙니다."
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-RUNS-NONCANONICAL}, {fact-id: F-RUN-WORKSPACE}, {fact-id: F-PORTABLE-OUTPUT}]
|
||||
status: supported
|
||||
|
||||
- id: C-ASSET-PROMOTION
|
||||
type: factual
|
||||
statement: GitHub에서 지속되는 gallery가 필요하면 검토된 파일을 `examples/` 또는 별도 versioned 문서 asset 경로로 승격하고, provenance와 manifest를 함께 갱신해야 합니다.
|
||||
section: artifacts
|
||||
sources: [{fact-id: F-RUNS-NONCANONICAL}]
|
||||
status: supported
|
||||
|
||||
- id: C-LAYER-OWNERSHIP
|
||||
type: factual
|
||||
statement: 이 소유권 지도에서 `.agents/.codex`는 adapter, `harnesses`는 capability 구현, `packages`는 contract와 runtime, `integrations`는 publication target을 담당합니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-REPOSITORY-LAYERS}]
|
||||
status: supported
|
||||
|
||||
- id: C-DEPENDENCY-DIRECTION
|
||||
type: factual
|
||||
statement: 정본 의존 방향은 adapter → harnesses → packages이며, `workflow-runtime`은 handler registry를 통해 harness를 실행하고 frozen projection만 integrations로 보냅니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-REPOSITORY-LAYERS}, {fact-id: F-SIBLING-HARNESSES}, {fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-CONTENT-MANIFEST
|
||||
type: factual
|
||||
statement: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
|
||||
section: verification
|
||||
sources: [{fact-id: F-EXAMPLE-CHAIN}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-CONTENT-MANIFEST
|
||||
type: factual
|
||||
statement: "결과: `VALID`, exit code 0."
|
||||
section: verification
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-ARTIFACT-SET
|
||||
type: factual
|
||||
statement: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERSIONED-VISUALS}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-ARTIFACT-SET
|
||||
type: factual
|
||||
statement: 이 검증은 체크인된 contract fixture를 대상으로 하며 fresh renderer execution을 대신하지 않습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERSIONED-VISUALS}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-LAYOUT-TEST
|
||||
type: factual
|
||||
statement: python3 -m unittest tests.conformance.test_repository_layout
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-LAYOUT-TEST
|
||||
type: factual
|
||||
statement: "결과: 18개 test가 통과했습니다."
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-FULL-SUITE
|
||||
type: factual
|
||||
statement: python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}]
|
||||
status: supported
|
||||
|
||||
- id: C-FULL-SUITE-SCOPE
|
||||
type: factual
|
||||
statement: 전체 suite는 이번 README 작업에서 재실행하지 않았습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}]
|
||||
status: supported
|
||||
|
||||
- id: C-E2E-PREREQUISITES
|
||||
type: factual
|
||||
statement: Renderer-backed E2E는 외부 Java/Gradle evidence repository, 외부 source document 또는 scope별 expert review 파일을 요구합니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-E2E-INPUTS}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-PACKAGING
|
||||
type: factual
|
||||
statement: dependency packaging manifest와 version pin이 없으므로 README는 임의의 패키지 설치 명령이나 최소 버전을 만들지 않습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-NO-PACKAGE-MANIFEST}, {fact-id: F-PREREQUISITES}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-RUNS
|
||||
type: factual
|
||||
statement: 실제 PNG·SVG·HTML·Markdown 샘플은 로컬 `runs/`에 있지만 clean checkout이나 GitHub 링크의 영속성을 보장하지 않습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-RUNS-NONCANONICAL}, {fact-id: F-LOCAL-CROSS-HARNESS-OUTPUT}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-BENCHMARKS
|
||||
type: factual
|
||||
statement: document-writing과 image-generation suite는 corpus만 정의되고 결과가 pending입니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-BENCHMARK-MATURITY}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-HYBRID
|
||||
type: factual
|
||||
statement: "`d2-svg-layer-compositor`의 자동 16-case 증거는 PASS지만 human Gate 3는 `PENDING`입니다."
|
||||
section: limitations
|
||||
sources: [{fact-id: F-HYBRID-PENDING}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-E2E
|
||||
type: factual
|
||||
statement: 전체 품질·dependency-direction·redraw 경로는 이 저장소만으로 완결되지 않고 외부 evidence/source와 완료된 expert review를 요구합니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-E2E-INPUTS}]
|
||||
status: supported
|
||||
|
||||
- id: C-DOCUMENTATION-MAP
|
||||
type: factual
|
||||
statement: 정본 설계는 `ARCHITECTURE.md`, 문서 색인은 `docs/README.md`, 실행 작업공간 정책은 `runs/README.md`에 있습니다.
|
||||
section: documentation
|
||||
sources: [{fact-id: F-REPOSITORY-LAYERS}, {fact-id: F-RUN-WORKSPACE}]
|
||||
status: supported
|
||||
@@ -0,0 +1,13 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
profile: generic
|
||||
repository-snapshot-hash: sha256:d65d7446cad11d46dabd2080c8393059f36fab426f4d62f18183b2c144c3de29
|
||||
artifacts:
|
||||
readme-request.yaml: sha256:0519446d82eff751f66484c9914405c2eeb9f76fcc3215b5a3474966cd817d66
|
||||
repository-facts.yaml: sha256:92a9f4f57f2ee17521fd80c718716025349fd1fb47e1145597475b0dc5ee0d02
|
||||
readme-brief.yaml: sha256:76e14ebd90aa11f052f69a05f61e2fed2c95885b15b3801082870ff341b84585
|
||||
readme-outline.yaml: sha256:331fdd38611d0301cc08960ba3f355e0787591042499bc888bcd335dc73899ce
|
||||
README.candidate.md: sha256:bb63802996c738e926449e65ee9319825b4bf4f2ab3379ee31afa85e1d5c3cc4
|
||||
claim-map.yaml: sha256:8156e3921c056a5d5a13aff31e400be758c8f9c4cf4b84ded92554b9325d0824
|
||||
visual-plan.yaml: sha256:d3d394a7d83a0757a3edd196721808a37e61ec3f637c2f41d5ffc28ac9997bd4
|
||||
review-findings.yaml: sha256:91840232609197295c642263473c3752f9f0aafee4c6e64c565f32ba679a25a4
|
||||
@@ -0,0 +1,59 @@
|
||||
schema-version: 1
|
||||
project-profile:
|
||||
primary: generic
|
||||
secondary:
|
||||
- multi-capability content workflow
|
||||
- contract-driven Python system
|
||||
audiences:
|
||||
primary:
|
||||
- 콘텐츠 하네스의 적용 범위와 실행 방법을 평가하는 개발자
|
||||
- document-writing, technical-visualization, image-generation 흐름에 기여하는 개발자
|
||||
secondary:
|
||||
- 생성 문서와 시각 산출물의 계약·검증 방식을 검토하는 기술 리더
|
||||
reader-outcomes:
|
||||
- 네 capability의 책임과 서로 호출하지 않는 경계를 설명할 수 있다.
|
||||
- 체크인된 Clean Architecture 예제를 검증하고 계획 결과를 확인할 수 있다.
|
||||
- 버전 관리되는 fixture와 무시되는 로컬 생성 산출물을 혼동하지 않는다.
|
||||
- 변경하려는 계약·하네스·런타임·통합 어댑터의 소유 경로를 찾을 수 있다.
|
||||
- 현재 의존성, 검증 수준, qualification 한계를 확인할 수 있다.
|
||||
project-story:
|
||||
value-proposition: 자연어 콘텐츠 요청을 문서 계획, 기술 시각화, 유기적 이미지, 검토된 publication output으로 연결하되 capability별 책임과 증거 경계를 파일 계약으로 유지한다.
|
||||
problem: 문서 작성과 정확한 기술 도형, 유기적 이미지 생성, 최종 통합을 한 흐름에서 다루면서도 sibling capability 사이의 의미·검토·실행 책임이 섞이지 않아야 한다.
|
||||
target-reader: 저장소를 평가·실행하거나 capability와 contract에 기여하는 개발자
|
||||
notable-traits:
|
||||
- text: document-writing, technical-visualization, image-generation은 sibling이며 workflow-runtime만 라우팅과 DAG 실행을 소유한다.
|
||||
fact-ids: [F-SIBLING-HARNESSES, F-ROUTING]
|
||||
- text: ContentJobRequest에서 ArtifactSet과 publication projection까지 단계별 계약이 분리돼 있다.
|
||||
fact-ids: [F-CONTRACT-CHAIN, F-INTEGRATIONS]
|
||||
- text: technical visualization은 의미 모델과 target별 rendition을 묶고, image generation은 exact technical geometry를 의도적으로 거부한다.
|
||||
fact-ids: [F-CAPABILITY-TECHNICAL, F-CAPABILITY-IMAGE]
|
||||
- text: 새 실행은 이전 결과를 검색하거나 재사용하지 않고 목적별 immutable run workspace를 할당한다.
|
||||
fact-ids: [F-RUN-WORKSPACE]
|
||||
- text: 로컬 테스트에는 문서·PNG·SVG가 함께 생성된 사례가 있지만 runs 경로는 무시되는 운영 데이터다.
|
||||
fact-ids: [F-LOCAL-CROSS-HARNESS-OUTPUT, F-LOCAL-DOCUMENT-VISUALIZATION, F-LOCAL-IMAGE-OUTPUT, F-RUNS-NONCANONICAL]
|
||||
maturity: 핵심 계약, 세 capability handler, runtime routing, 통합 adapter, 테스트와 로컬 실행 산출물이 구현돼 있다. 다만 일부 benchmark 결과와 d2-svg-layer-compositor의 사람 qualification은 완료되지 않았다.
|
||||
limitations:
|
||||
- 저장소에는 의존성 버전과 설치를 고정하는 packaging manifest가 없다.
|
||||
- 전체 end-to-end 경로에는 외부 evidence repository와 별도 expert review 파일이 필요하다.
|
||||
- runs 아래 실제 생성 결과는 로컬·ignored 데이터이므로 GitHub README의 영구 이미지 링크로 사용할 수 없다.
|
||||
- d2-svg-layer-compositor는 자동 증거가 PASS지만 사람 Gate 3가 PENDING인 qualification candidate다.
|
||||
narrative-variant: product
|
||||
reader-journey:
|
||||
- reader-question: 이 저장소는 무엇을 만들며 누구를 위한 것인가?
|
||||
section-id: overview
|
||||
- reader-question: 각 capability는 무엇을 소유하고 어디서 경계가 갈리는가?
|
||||
section-id: capabilities
|
||||
- reader-question: 가장 짧은 검증 경로로 구현 상태를 어떻게 확인하는가?
|
||||
section-id: quick-start
|
||||
- reader-question: 요청이 계획·생성·검토·publication으로 어떻게 이동하는가?
|
||||
section-id: execution-model
|
||||
- reader-question: 생성된 이미지·문서·기술 시각화는 어디서 어떻게 확인하는가?
|
||||
section-id: artifacts
|
||||
- reader-question: 기능을 수정하려면 어느 디렉터리와 계약을 봐야 하는가?
|
||||
section-id: architecture
|
||||
- reader-question: 명령의 실제 검증 수준과 전체 테스트 진입점은 무엇인가?
|
||||
section-id: verification
|
||||
- reader-question: 현재 과장 없이 밝혀야 할 제약과 qualification 상태는 무엇인가?
|
||||
section-id: limitations
|
||||
- reader-question: 더 깊은 설계·운영·benchmark 문서는 어디에 있는가?
|
||||
section-id: documentation
|
||||
@@ -0,0 +1,146 @@
|
||||
schema-version: 1
|
||||
sections:
|
||||
- id: overview
|
||||
title-guidance: Content Harness
|
||||
level: 1
|
||||
purpose: 프로젝트의 구체적 결과, provider-neutral 경계, 대상 독자를 첫 화면에서 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 한 문단 정체성과 가치
|
||||
- 네 capability와 publication 결과를 한 줄로 요약
|
||||
- 대상 독자와 README가 제공하는 최소 경로
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 첫 화면에 별도 hero 이미지가 이해를 실질적으로 높이는가?
|
||||
rationale: 저장소 소유의 영구 hero asset이 없고 로컬 runs 이미지는 ignored이므로 구체적 설명이 더 정확하다.
|
||||
|
||||
- id: capabilities
|
||||
title-guidance: 책임이 섞이지 않는 네 capability
|
||||
level: 2
|
||||
purpose: document writing, technical visualization, image generation, workflow runtime의 책임·출력·금지 경계를 비교한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 네 capability 비교표
|
||||
- 기술 도형과 유기적 이미지의 선택 기준
|
||||
- integrations가 publication projection만 소비한다는 경계
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: capability별 책임을 비교할 때 별도 그림이 표보다 나은가?
|
||||
rationale: 책임·입력·출력·금지를 정확히 짝짓는 표가 탐색과 유지보수에 더 적합하다.
|
||||
|
||||
- id: quick-start
|
||||
title-guidance: 2분 검증
|
||||
level: 2
|
||||
purpose: 의존성 전제와 체크인된 예제의 contract validation 및 front-door 계획을 재현한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- Python과 feature-specific 도구 전제
|
||||
- canonical install manifest 부재 고지
|
||||
- 실행 확인된 content-job validation
|
||||
- 실행 확인된 front-door plan
|
||||
- 기대 결과와 production execution이 아님을 명시
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 짧은 복사 실행 경로에 그림이 필요한가?
|
||||
rationale: 두 command와 기대 결과를 순서대로 제시하는 편이 더 직접적이다.
|
||||
|
||||
- id: execution-model
|
||||
title-guidance: 요청에서 publication까지
|
||||
level: 2
|
||||
purpose: contract chain, routing, sibling harness, ArtifactSet, integration의 데이터 흐름과 경계를 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- ContentJobRequest에서 publication projection까지의 단계
|
||||
- technical-only, image-only, hybrid routing
|
||||
- runtime만 sibling 결과를 조립한다는 관계
|
||||
- 검토되지 않은 결과가 publication으로 넘어가지 않는 경계
|
||||
visual-slot:
|
||||
decision: include
|
||||
reader-question: 세 sibling branch와 contract chain이 어디서 합류하는가?
|
||||
rationale: 선형 설명만으로는 document, technical, image branch와 runtime 소유 합류점을 동시에 파악하기 어렵다.
|
||||
purpose: 요청과 contract가 workflow-runtime을 통해 sibling capability로 분기하고 검토된 publication으로 합류하는 흐름을 보여준다.
|
||||
|
||||
- id: artifacts
|
||||
title-guidance: 생성 산출물 둘러보기
|
||||
level: 2
|
||||
purpose: versioned fixture, 로컬 테스트 생성 문서·이미지·기술 시각화, portable output의 차이를 명시한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 체크인된 Clean Architecture contract fixture 링크
|
||||
- 현재 작업 사본에서 확인된 cross-harness output 유형과 경로
|
||||
- document visualization 및 best-of-three image 예시
|
||||
- runs가 ignored이고 정본이 아니라는 경고
|
||||
- GitHub에 보일 gallery로 쓰려면 examples 또는 docs로 승격해야 한다는 안내
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 로컬 test output을 README에 직접 임베드해도 지속 가능한가?
|
||||
rationale: runs 전체가 ignored라 링크가 clean checkout과 GitHub에서 깨지므로 경로·유형·승격 정책을 표로 설명한다.
|
||||
|
||||
- id: architecture
|
||||
title-guidance: 저장소 구조와 변경 위치
|
||||
level: 2
|
||||
purpose: adapters, harnesses, packages, integrations, tests, examples, benchmarks, runs의 소유권과 의존 방향을 연결한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 주요 디렉터리 책임 표
|
||||
- canonical dependency direction
|
||||
- 계약·capability·runtime·publication 변경 시 시작 위치
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 기여 위치를 찾는 데 두 번째 구조 그림이 필요한가?
|
||||
rationale: 이미 execution flow visual이 있고 경로·책임 표가 파일 탐색에는 더 정확하다.
|
||||
|
||||
- id: verification
|
||||
title-guidance: 검증 명령과 증거 수준
|
||||
level: 2
|
||||
purpose: 이번 README 작업에서 실행한 명령과 발견만 한 전체 suite를 분리해 제시한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 실행 확인한 contract, ArtifactSet, layout test 명령
|
||||
- full unittest discovery command는 미실행임을 명시
|
||||
- end-to-end는 외부 evidence와 review 파일이 필요하다는 링크
|
||||
- 명령별 성공 신호
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 검증 수준 선택에 그림이 필요한가?
|
||||
rationale: 목적·명령·성공 신호·실행 수준을 짝지은 표가 더 명료하다.
|
||||
|
||||
- id: limitations
|
||||
title-guidance: 현재 상태와 한계
|
||||
level: 2
|
||||
purpose: dependency metadata, ignored outputs, benchmark maturity, external inputs, qualification 상태를 과장 없이 밝힌다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- canonical dependency installer와 version pin 부재
|
||||
- runs 출력의 비영속성
|
||||
- document/image benchmark 결과 pending
|
||||
- d2-svg-layer-compositor 사람 Gate 3 pending
|
||||
- 전체 unittest suite는 이번 README 작업에서 재실행하지 않았다는 검증 범위
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 현재 제약을 이해하는 데 그림이 필요한가?
|
||||
rationale: 상태·영향·후속 행동을 한 줄씩 연결한 목록이 더 정확하다.
|
||||
|
||||
- id: documentation
|
||||
title-guidance: 문서와 정본 지도
|
||||
level: 2
|
||||
purpose: architecture, runtime workspace, capability guide, examples, benchmark로 목적별 이동 경로를 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- ARCHITECTURE.md와 docs/README.md
|
||||
- runs/README.md
|
||||
- 세 harness README와 workflow runtime README
|
||||
- examples, end-to-end, benchmark index
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 세부 정본을 찾는 데 시각화가 필요한가?
|
||||
rationale: 목적별 상대 링크 목록이 GitHub 탐색과 유지보수에 가장 적합하다.
|
||||
@@ -0,0 +1,51 @@
|
||||
schema-version: 1
|
||||
target:
|
||||
repository: /home/donghyeon/workspace/ai-tool/image-haness
|
||||
readme-path: README.md
|
||||
mode: bootstrap
|
||||
profile-override: generic
|
||||
project-intent:
|
||||
purpose: 저장소의 문서 작성, 기술 시각화, 이미지 생성, 통합 실행 흐름을 실제 구현과 검증 가능한 산출물에 근거해 한눈에 설명한다.
|
||||
positioning: 콘텐츠 하네스를 평가·실행하려는 개발자와 각 capability에 기여하려는 개발자를 위한 저장소 진입 문서다.
|
||||
maturity: 체크인된 구현·테스트·실행 산출물과 현재 의존성 및 한계를 과장 없이 구분해 문서화한다.
|
||||
audience:
|
||||
primary:
|
||||
- 콘텐츠 하네스의 적용 범위와 실행 방법을 평가하는 개발자
|
||||
- document-writing, technical-visualization, image-generation 흐름에 기여하는 개발자
|
||||
secondary:
|
||||
- 생성 문서와 시각 산출물의 계약·검증 방식을 검토하는 기술 리더
|
||||
reader-actions:
|
||||
- 프로젝트가 해결하는 문제와 capability 경계를 빠르게 파악한다.
|
||||
- 대표 예제를 정적으로 검증하고 전체 테스트 진입점을 찾는다.
|
||||
- 테스트로 생성된 이미지, 문서, 기술 시각화의 실제 예시를 탐색한다.
|
||||
- 주요 패키지와 하네스의 책임 및 실행 데이터 흐름을 이해한다.
|
||||
- 필수·선택 도구와 현재 한계를 확인한다.
|
||||
content-policy:
|
||||
language: ko-KR
|
||||
tone: 간결하고 기술적이며 검증 수준과 산출물 성격을 명확히 구분하는 설명체
|
||||
target-length: long
|
||||
preserve-existing-copy: false
|
||||
detail-docs-policy: summary-and-link
|
||||
visual-policy:
|
||||
mode: when-useful
|
||||
max-visuals: 2
|
||||
preferred-formats:
|
||||
- repository-owned raster or SVG artifact
|
||||
- mermaid
|
||||
placeholder-format: HTML 주석 기반 제작 사양; 검증된 기존 산출물은 저장소 상대 경로로 직접 표시
|
||||
must-include:
|
||||
- 프로젝트 개요와 대상 독자
|
||||
- document-writing, technical-visualization, image-generation, workflow-runtime의 책임과 연결 관계
|
||||
- 대표 검증 또는 실행 흐름과 명령별 검증 수준
|
||||
- 테스트로 생성된 이미지, 문서, 기술 시각화 산출물의 실제 경로와 성격
|
||||
- 저장소 구조와 기여 위치
|
||||
- 필수 및 선택 도구
|
||||
- runs 디렉터리의 실행 기록 성격과 정본으로 사용하지 않는다는 경계
|
||||
- 현재 구현 상태와 확인된 한계
|
||||
- ARCHITECTURE.md와 docs 색인 링크
|
||||
must-exclude:
|
||||
- 저장소 근거가 없는 기능·버전·성능·품질 우위 주장
|
||||
- 실패·중간 후보 산출물을 성공 예시로 오인시키는 표현
|
||||
- 비밀 값 또는 개인 환경의 절대 경로
|
||||
- 상세 설계 이력과 모든 run 파일의 장문 나열
|
||||
protected-sections: []
|
||||
@@ -0,0 +1,583 @@
|
||||
schema-version: 1
|
||||
repository-snapshot-hash: sha256:d65d7446cad11d46dabd2080c8393059f36fab426f4d62f18183b2c144c3de29
|
||||
project-name: Content Harness
|
||||
languages: [Python, YAML, JSON, Markdown]
|
||||
facts:
|
||||
- id: F-IDENTITY
|
||||
category: identity
|
||||
key: project-purpose
|
||||
value:
|
||||
name: Content Harness
|
||||
purpose: provider-neutral technical-document planning, exact technical visualization, organic image generation, and accepted-asset publication
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: README.md
|
||||
line-start: 1
|
||||
line-end: 14
|
||||
source-kind: project-documentation
|
||||
- path: packages/workflow-runtime/handlers.yaml
|
||||
line-start: 1
|
||||
line-end: 8
|
||||
source-kind: handler-registry
|
||||
|
||||
- id: F-REPOSITORY-LAYERS
|
||||
category: architecture
|
||||
key: canonical-layer-ownership
|
||||
value:
|
||||
.agents-and-.codex: thin provider discovery adapters
|
||||
harnesses: capability policy and implementation canon
|
||||
packages: contracts and runtime canon
|
||||
integrations: publication target adapters
|
||||
tests: repository-wide validation and golden artifacts
|
||||
examples: versioned executable examples
|
||||
benchmarks: evaluation suites and failure corpora
|
||||
runs: ignored local workflow data
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 3
|
||||
line-end: 28
|
||||
source-kind: architecture-documentation
|
||||
- path: .codex/agents/natural-prose-reviewer.toml
|
||||
line-start: 1
|
||||
line-end: 9
|
||||
source-kind: thin-provider-adapter
|
||||
|
||||
- id: F-SIBLING-HARNESSES
|
||||
category: architecture
|
||||
key: sibling-harness-runtime-boundary
|
||||
value:
|
||||
handlers: [document-writing, technical-visualization, image-generation]
|
||||
rule: sibling harnesses return plans or results and do not call one another
|
||||
runtime-responsibility: validation, routing, DAG execution, retries, result transfer, integration, and events
|
||||
execution-boundary: workflow-runtime -> handlers.yaml -> HarnessHandler -> immutable JobResult
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 30
|
||||
line-end: 53
|
||||
source-kind: architecture-documentation
|
||||
- path: packages/workflow-runtime/handlers.yaml
|
||||
line-start: 1
|
||||
line-end: 8
|
||||
source-kind: handler-registry
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
line-start: 43
|
||||
line-end: 51
|
||||
source-kind: conformance-test
|
||||
|
||||
- id: F-CAPABILITY-DOCUMENT
|
||||
category: capability
|
||||
key: document-writing
|
||||
value:
|
||||
owns: [narrative, audience, evidence linkage, visual-opportunity detection, figure context]
|
||||
operations: [document-writing.intake, document-writing.analyze, document-writing.plan, document-writing.revise, document-writing.draft]
|
||||
outputs: [content-job-request, publication-draft, content-manifest, narrative-plan, narrative-analysis, reviews, visual-requests]
|
||||
boundary: never edits the source document in place and does not select renderers or generate imagery
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: harnesses/document-writing/README.md
|
||||
line-start: 3
|
||||
line-end: 29
|
||||
source-kind: capability-documentation
|
||||
- path: harnesses/document-writing/capability.yaml
|
||||
line-start: 1
|
||||
line-end: 22
|
||||
source-kind: capability-declaration
|
||||
- path: harnesses/document-writing/handler.py
|
||||
line-start: 253
|
||||
line-end: 345
|
||||
symbol: DocumentWritingHandler
|
||||
source-kind: implementation
|
||||
|
||||
- id: F-CAPABILITY-TECHNICAL
|
||||
category: capability
|
||||
key: technical-visualization
|
||||
value:
|
||||
owns: [evidence-grounded semantic models, visual grammar, deterministic rendering, target-specific renditions]
|
||||
executable-visual-types: [dependency-graph, runtime-sequence]
|
||||
renderer: d2
|
||||
output-profiles: [document, presentation]
|
||||
acceptance-boundary: separate exact-input technical-semantic and technical-visual expert reviews are required
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: harnesses/technical-visualization/README.md
|
||||
line-start: 3
|
||||
line-end: 23
|
||||
source-kind: capability-documentation
|
||||
- path: harnesses/technical-visualization/capability.yaml
|
||||
line-start: 1
|
||||
line-end: 23
|
||||
source-kind: capability-declaration
|
||||
- path: harnesses/technical-visualization/handler.py
|
||||
line-start: 904
|
||||
line-end: 962
|
||||
symbol: TechnicalVisualizationHandler
|
||||
source-kind: implementation
|
||||
|
||||
- id: F-CAPABILITY-IMAGE
|
||||
category: capability
|
||||
key: image-generation
|
||||
value:
|
||||
owns: [organic raster imagery, photography, illustration, bounded candidate search, local repair]
|
||||
operations: [image-generation.generate, image-generation.generate-component]
|
||||
production-model: three hashed candidates, pairwise comparison, explicit selection, and at most one bounded repair
|
||||
excluded: [exact architecture relations, charts, state transitions, long exact text, evidence-derived technical geometry]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: harnesses/image-generation/README.md
|
||||
line-start: 3
|
||||
line-end: 26
|
||||
source-kind: capability-documentation
|
||||
- path: harnesses/image-generation/capability.yaml
|
||||
line-start: 1
|
||||
line-end: 24
|
||||
source-kind: capability-declaration
|
||||
- path: harnesses/image-generation/handler.py
|
||||
line-start: 246
|
||||
line-end: 301
|
||||
symbol: ImageGenerationHandler
|
||||
source-kind: implementation
|
||||
|
||||
- id: F-ROUTING
|
||||
category: architecture
|
||||
key: visual-routing-policy
|
||||
value:
|
||||
technical-only: technical-visualization
|
||||
image-only: image-generation
|
||||
both: hybrid DAG
|
||||
neither: BLOCKED_UNRESOLVED
|
||||
explicit-conflict: ROUTING_CONFLICT
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 100
|
||||
line-end: 118
|
||||
source-kind: architecture-documentation
|
||||
- path: packages/workflow-runtime/policies/routing.yaml
|
||||
line-start: 27
|
||||
line-end: 31
|
||||
source-kind: runtime-policy
|
||||
|
||||
- id: F-CONTRACT-CHAIN
|
||||
category: architecture
|
||||
key: content-to-publication-contract-chain
|
||||
value:
|
||||
- ContentJobRequest
|
||||
- Content Manifest
|
||||
- Narrative Plan
|
||||
- Visual Request
|
||||
- ArtifactSet
|
||||
- frozen publication projection
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 69
|
||||
line-end: 98
|
||||
source-kind: architecture-documentation
|
||||
|
||||
- id: F-INTEGRATIONS
|
||||
category: capability
|
||||
key: publication-adapters
|
||||
value:
|
||||
targets: [Markdown, Slides, HTML]
|
||||
input: one runtime-selected frozen publication projection
|
||||
boundary: adapters do not choose content, route, renderer, provider, or visual grammar
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: integrations/README.md
|
||||
line-start: 1
|
||||
line-end: 11
|
||||
source-kind: integration-documentation
|
||||
|
||||
- id: F-EXAMPLE-CHAIN
|
||||
category: examples
|
||||
key: checked-in-clean-architecture-chain
|
||||
value:
|
||||
root: examples/clean-architecture
|
||||
contracts: [content-job-request.yaml, content-manifest.yaml, narrative-plan.yaml, reference-registry.yaml, visual-request.yaml, workflow-request.content-job.yaml, workflow-request.visual.yaml, artifact/attempt-01/artifact-set.yaml]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
line-start: 480
|
||||
line-end: 496
|
||||
source-kind: conformance-test
|
||||
- path: examples/clean-architecture/content-job-request.yaml
|
||||
source-kind: versioned-example
|
||||
|
||||
- id: F-VERSIONED-VISUALS
|
||||
category: artifacts
|
||||
key: checked-in-technical-visual-contract-fixture
|
||||
value:
|
||||
artifact-status: accepted
|
||||
integration-status: ready
|
||||
scope: contract-only fixture rather than renderer-backed golden comparison
|
||||
renditions:
|
||||
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.svg, target: document, dimensions: 820x460}
|
||||
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation.svg, target: presentation, dimensions: 1600x900}
|
||||
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation-step-1.svg, target: presentation-reveal-step, dimensions: 1600x900}
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: examples/clean-architecture/artifact/attempt-01/artifact-set.yaml
|
||||
line-start: 2
|
||||
line-end: 78
|
||||
source-kind: artifact-manifest
|
||||
- path: tests/golden/dependency-directions/README.md
|
||||
line-start: 1
|
||||
line-end: 7
|
||||
source-kind: golden-fixture-documentation
|
||||
|
||||
- id: F-RUN-WORKSPACE
|
||||
category: runtime
|
||||
key: fresh-run-allocation
|
||||
value:
|
||||
path: runs/<purpose>/run-<YYYYMMDDTHHMMSSZ>-NNN/
|
||||
semantics: each valid fresh intake or execution creates a new immutable workspace; matching request or workflow ids do not authorize reuse
|
||||
optional-output: <run-root>/output/
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/README.md
|
||||
line-start: 1
|
||||
line-end: 32
|
||||
source-kind: runtime-workspace-policy
|
||||
- path: packages/workflow-runtime/README.md
|
||||
line-start: 86
|
||||
line-end: 98
|
||||
source-kind: runtime-documentation
|
||||
|
||||
- id: F-PORTABLE-OUTPUT
|
||||
category: artifacts
|
||||
key: reviewed-output-bundle
|
||||
value:
|
||||
location: <run-root>/output/
|
||||
entrypoint: index.html
|
||||
manifest: manifest.yaml
|
||||
condition: reviewed publication draft or accepted integration-ready ArtifactSet
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: packages/workflow-runtime/README.md
|
||||
line-start: 216
|
||||
line-end: 221
|
||||
source-kind: runtime-documentation
|
||||
- path: tests/runtime/test_output_bundle.py
|
||||
line-start: 176
|
||||
line-end: 204
|
||||
symbol: test_bundle_is_portable_and_manifest_hashes_match
|
||||
source-kind: runtime-test
|
||||
|
||||
- id: F-LOCAL-CROSS-HARNESS-OUTPUT
|
||||
category: artifacts
|
||||
key: local-cross-harness-test-output
|
||||
value:
|
||||
root: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output
|
||||
generated-document: [README.md, final-document.md, index.html, preview.png]
|
||||
technical-visualization: [assets/dependency-directions.document.svg, assets/dependency-directions.presentation.svg]
|
||||
image-generation: [assets/editorial-workbench.document.png, assets/editorial-workbench.presentation.png, assets/image-candidates.png]
|
||||
validation: validation-summary.yaml
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/manifest.yaml
|
||||
line-start: 1
|
||||
line-end: 35
|
||||
source-kind: local-generated-output-manifest
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/README.md
|
||||
line-start: 1
|
||||
line-end: 12
|
||||
source-kind: local-generated-document
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/preview.png
|
||||
source-kind: local-generated-preview
|
||||
|
||||
- id: F-LOCAL-DOCUMENT-VISUALIZATION
|
||||
category: artifacts
|
||||
key: local-document-visualization-test-output
|
||||
value:
|
||||
root: runs/docvis-20260716-executable-clean-architecture-part1
|
||||
document-output: document/part1-integrated.html
|
||||
figures: [fig-invisible-shortcut, fig-enforcement-gradient]
|
||||
formats: [desktop-SVG, mobile-SVG, PNG-fallback]
|
||||
previews: [integrated-previews/part1-desktop.png, integrated-previews/part1-mobile-v2.png]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/docvis-20260716-executable-clean-architecture-part1/delivery/delivery-manifest.yaml
|
||||
line-start: 1
|
||||
line-end: 24
|
||||
source-kind: local-delivery-manifest
|
||||
- path: runs/docvis-20260716-executable-clean-architecture-part1/figures/fig-enforcement-gradient/asset-manifest.yaml
|
||||
line-start: 1
|
||||
line-end: 30
|
||||
source-kind: local-figure-manifest
|
||||
|
||||
- id: F-LOCAL-IMAGE-OUTPUT
|
||||
category: artifacts
|
||||
key: local-best-of-three-image-test-output
|
||||
value:
|
||||
root: runs/img-20260716-japanese-animation-test
|
||||
generation-candidates: 3
|
||||
selected-attempt: 2
|
||||
selected-output: outputs/final-selected.png
|
||||
selection-label: BEST_OF_N_PASS
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/img-20260716-japanese-animation-test/selection.json
|
||||
line-start: 1
|
||||
line-end: 64
|
||||
source-kind: local-selection-record
|
||||
- path: runs/img-20260716-japanese-animation-test/outputs/final-selected.png
|
||||
source-kind: local-generated-image
|
||||
|
||||
- id: F-RUNS-NONCANONICAL
|
||||
category: limitation
|
||||
key: local-run-durability
|
||||
value: runs/** is ignored local operational data, not a cache or source of truth; reusable examples belong under examples, regression oracles under tests/golden, and evaluation corpora under benchmarks
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .gitignore
|
||||
line-start: 5
|
||||
line-end: 7
|
||||
source-kind: ignore-policy
|
||||
- path: runs/README.md
|
||||
line-start: 1
|
||||
line-end: 7
|
||||
source-kind: runtime-workspace-policy
|
||||
- path: docs/README.md
|
||||
line-start: 23
|
||||
line-end: 35
|
||||
source-kind: documentation-policy
|
||||
|
||||
- id: F-PREREQUISITES
|
||||
category: prerequisites
|
||||
key: runtime-tools
|
||||
value:
|
||||
language: Python 3
|
||||
python-packages: [PyYAML, jsonschema, Pillow]
|
||||
feature-specific-tools:
|
||||
technical-rendering: D2
|
||||
SVG-preview: Chrome or Chromium
|
||||
version-pins: not declared
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: README.md
|
||||
line-start: 151
|
||||
line-end: 153
|
||||
source-kind: project-documentation
|
||||
- path: packages/schema-support/src/contract_support.py
|
||||
line-start: 13
|
||||
line-end: 14
|
||||
source-kind: dependency-import
|
||||
- path: packages/export-validator/src/validate_export.py
|
||||
line-start: 1
|
||||
line-end: 14
|
||||
source-kind: dependency-import
|
||||
- path: harnesses/technical-visualization/renderers/d2/renderer.py
|
||||
line-start: 206
|
||||
line-end: 213
|
||||
source-kind: renderer-implementation
|
||||
- path: harnesses/image-generation/scripts/render_svg_preview.py
|
||||
line-start: 18
|
||||
line-end: 31
|
||||
source-kind: preview-implementation
|
||||
|
||||
- id: F-NO-PACKAGE-MANIFEST
|
||||
category: limitation
|
||||
key: dependency-installation-metadata
|
||||
value: no pyproject.toml, requirements.txt, setup.py, setup.cfg, Pipfile, poetry.lock, or uv.lock is present; dependency versions and one canonical installation command cannot be evidenced
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .
|
||||
source-kind: repository-file-scan
|
||||
|
||||
- id: F-TEST-INVENTORY
|
||||
category: tests
|
||||
key: unittest-suite
|
||||
value:
|
||||
framework: unittest
|
||||
observed-test-methods: 300
|
||||
groups: [conformance, contracts, failure_injection, harnesses, integrations, runtime]
|
||||
declared-latest-full-run: 300 tests passed in repository refactoring review
|
||||
current-readme-run-check: repository-layout module passed 18 tests
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: tests
|
||||
source-kind: test-directory-scan
|
||||
- path: docs/refactoring-review.md
|
||||
line-start: 76
|
||||
line-end: 91
|
||||
source-kind: declared-verification-report
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
source-kind: executed-test-module
|
||||
|
||||
- id: F-EXECUTED-QUICK-CHECKS
|
||||
category: verification
|
||||
key: readme-authoring-session-executions
|
||||
value:
|
||||
date: 2026-07-18
|
||||
content-job-request-validation: {exit-code: 0}
|
||||
content-manifest-validation: {exit-code: 0, output: VALID}
|
||||
front-door-content-plan: {exit-code: 0, primary-capability: document-writing}
|
||||
artifact-set-validation: {exit-code: 0, output: VALID}
|
||||
repository-layout-tests: {tests: 18, result: PASS}
|
||||
assertion-type: executed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: packages/content-job-contract/src/validate_content_job.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: packages/content-contract/src/validate_content.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: packages/workflow-runtime/src/content_runtime.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: packages/artifact-contract/src/validate_artifact_set.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
source-kind: executed-test-module
|
||||
|
||||
- id: F-E2E-INPUTS
|
||||
category: prerequisites
|
||||
key: end-to-end-external-inputs
|
||||
value:
|
||||
dependency-directions: [external Java/Gradle evidence repository, completed technical review file, completed narrative review file]
|
||||
part1-redraw: [external source document, completed expert review file]
|
||||
all-harness-quality: [external Java/Gradle evidence repository, stage-specific review files]
|
||||
assertion-type: declared
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: tests/end-to-end/README.md
|
||||
line-start: 68
|
||||
line-end: 139
|
||||
source-kind: end-to-end-documentation
|
||||
|
||||
- id: F-HYBRID-PENDING
|
||||
category: limitation
|
||||
key: d2-svg-layer-compositor-status
|
||||
value:
|
||||
automated-evidence: PASS
|
||||
human-qualification: PENDING
|
||||
production-status: qualification candidate, not qualified renderer
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: packages/workflow-runtime/policies/qualification.yaml
|
||||
line-start: 29
|
||||
line-end: 33
|
||||
source-kind: qualification-policy
|
||||
- path: benchmarks/hybrid-composition/results/d2-svg-layer-compositor-qualification.yaml
|
||||
line-start: 1
|
||||
line-end: 9
|
||||
source-kind: automated-qualification-result
|
||||
- path: benchmarks/hybrid-composition/results/d2-svg-layer-compositor-qualification.yaml
|
||||
line-start: 65
|
||||
line-end: 72
|
||||
source-kind: human-qualification-result
|
||||
|
||||
- id: F-BENCHMARK-MATURITY
|
||||
category: limitation
|
||||
key: qualification-corpus-status
|
||||
value:
|
||||
document-writing: corpus-defined-results-pending
|
||||
image-generation: corpus-defined-results-pending
|
||||
technical-visualization: dependency-directions comparison has unexecuted conditions and pending human preference
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: benchmarks/document-writing/suite.yaml
|
||||
line-start: 1
|
||||
line-end: 32
|
||||
source-kind: benchmark-suite
|
||||
- path: benchmarks/image-quality/suite.yaml
|
||||
line-start: 1
|
||||
line-end: 41
|
||||
source-kind: benchmark-suite
|
||||
- path: benchmarks/technical-visualization/results/dependency-directions-qualification.yaml
|
||||
line-start: 1
|
||||
line-end: 25
|
||||
source-kind: benchmark-result
|
||||
|
||||
- id: F-NO-GIT-METADATA
|
||||
category: limitation
|
||||
key: repository-snapshot
|
||||
value: the supplied directory has an empty .git directory, so no commit SHA or clean/dirty Git state can be established; the README run uses a repository content hash instead
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .
|
||||
source-kind: filesystem-and-git-probe
|
||||
|
||||
commands:
|
||||
- id: CMD-001
|
||||
command: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
||||
cwd: .
|
||||
source: {path: packages/content-job-contract/README.md, line-start: 21, line-end: 25}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-18; exit code 0
|
||||
level: isolated-execution
|
||||
limitations: [validates the checked-in ContentJobRequest only]
|
||||
|
||||
- id: CMD-002
|
||||
command: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 93, line-end: 96}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-18; exit code 0 and a document-writing plan was emitted
|
||||
level: isolated-execution
|
||||
limitations: [plans the checked-in request but does not execute production providers]
|
||||
|
||||
- id: CMD-003
|
||||
command: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 99, line-end: 102}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-18; exit code 0 and output VALID
|
||||
level: isolated-execution
|
||||
limitations: [validates the checked-in Content Manifest only]
|
||||
|
||||
- id: CMD-004
|
||||
command: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 114, line-end: 116}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-18; exit code 0 and output VALID
|
||||
level: isolated-execution
|
||||
limitations: [validates the checked-in contract fixture rather than a fresh renderer run]
|
||||
|
||||
- id: CMD-005
|
||||
command: python3 -m unittest tests.conformance.test_repository_layout
|
||||
cwd: .
|
||||
source: {path: tests/conformance/test_repository_layout.py}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-18; 18 tests passed
|
||||
level: isolated-execution
|
||||
limitations: [covers repository layout only, not the full suite]
|
||||
|
||||
- id: CMD-006
|
||||
command: python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 145, line-end: 149}
|
||||
verification:
|
||||
status: discovered
|
||||
method: located in the current root README and unittest tree
|
||||
level: static
|
||||
limitations: [not executed during this README rewrite; the refactoring review separately declares an earlier 300-test pass]
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"git-sha": null,
|
||||
"dirty": true,
|
||||
"diff-hash": "sha256:d65d7446cad11d46dabd2080c8393059f36fab426f4d62f18183b2c144c3de29",
|
||||
"scanned-at": null,
|
||||
"file-count": 560
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
schema-version: 1
|
||||
verdict: PASS
|
||||
score: 94
|
||||
scores:
|
||||
project-specificity:
|
||||
score: 5
|
||||
evidence:
|
||||
- "overview·capabilities: ContentJobRequest, sibling harness, workflow-runtime, ArtifactSet, frozen publication projection 등 이 저장소 고유의 책임과 계약을 첫 화면부터 구체적으로 설명한다. 근거: F-IDENTITY, F-SIBLING-HARNESSES, F-CONTRACT-CHAIN, F-INTEGRATIONS."
|
||||
- "artifacts: 체크인된 Clean Architecture fixture와 P6·docvis·best-of-three 로컬 결과를 실제 경로·산출물 유형·검토 상태로 구분한다. 근거: F-VERSIONED-VISUALS, F-LOCAL-CROSS-HARNESS-OUTPUT, F-LOCAL-DOCUMENT-VISUALIZATION, F-LOCAL-IMAGE-OUTPUT."
|
||||
reader-journey:
|
||||
score: 5
|
||||
evidence:
|
||||
- overview → capability 경계 → 2분 검증 → 실행 모델 → 산출물 → 변경 위치 → 검증 수준 → 한계 → 정본 문서 순서가 평가자와 기여자의 질문을 자연스럽게 해소한다.
|
||||
- artifacts와 limitations에서 ignored runs를 실제 결과의 탐색 위치로 안내하면서도 clean checkout·GitHub에서 지속되는 정본으로 오인하지 않도록 즉시 경계를 설명한다.
|
||||
technical-explanation:
|
||||
score: 5
|
||||
evidence:
|
||||
- "execution-model: contract chain, technical-only·image-only·hybrid routing, runtime-owned composition, expert review와 acceptance 경계를 책임 흐름으로 연결한다. 근거: F-CONTRACT-CHAIN, F-ROUTING, F-SIBLING-HARNESSES, F-CAPABILITY-TECHNICAL."
|
||||
- "architecture: adapter·harnesses·packages·integrations의 소유권과 adapter → harnesses → packages 의존 방향을 변경 위치 표 및 정본 링크와 함께 설명한다. 근거: F-REPOSITORY-LAYERS, F-SIBLING-HARNESSES, F-INTEGRATIONS."
|
||||
task-usability:
|
||||
score: 4
|
||||
evidence:
|
||||
- "quick-start: 전제 조건, packaging manifest 부재, 실행 위치가 명확한 두 명령, 기대 결과, front-door가 production provider 실행이 아니라는 범위를 한 경로로 제공한다."
|
||||
- "verification: CMD-001부터 CMD-005까지의 실제 exit 0 실행과 CMD-006의 명시적 미실행을 구분하고, fixture 검증·layout test가 전체 실행을 대신하지 않는다고 밝힌다. 다만 정본 설치 명령과 version pin이 없어 새 환경에서는 독자가 의존성을 별도로 준비해야 한다."
|
||||
prose-clarity:
|
||||
score: 4
|
||||
evidence:
|
||||
- 전체 문서는 짧은 문단, 경로·책임 표, 제한 목록으로 214줄의 긴 범위를 탐색 가능하게 유지하며 성공·accepted·ready·pending 상태를 과장 없이 구분한다.
|
||||
- capabilities와 execution-model 일부에서 contract·publication·rendition·provider 같은 영문 용어가 밀집하고, 실행 확인이 quick-start와 verification 두 곳에 나뉘지만 의미 중복은 제한적이고 섹션 목적은 분명하다.
|
||||
visual-judgment:
|
||||
score: 5
|
||||
evidence:
|
||||
- execution-model의 Mermaid는 세 sibling branch, runtime-owned hybrid 합류, reviewed output과 frozen projection의 관계를 한 화면에서 보여 주어 인접 문장만으로 파악하기 어려운 흐름을 보완한다.
|
||||
- "artifacts에서는 ignored runs의 PNG·SVG를 영구 gallery처럼 임베드하지 않고, versioned fixture만 상대 링크로 제공하며 asset 승격 조건을 설명해 시각적 매력보다 provenance와 링크 지속성을 우선한다. 근거: F-RUNS-NONCANONICAL, F-VERSIONED-VISUALS."
|
||||
hard-gates:
|
||||
passed: true
|
||||
failures: []
|
||||
reader-simulations:
|
||||
30-seconds:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- overview의 제목과 세 문단만으로 자연어 콘텐츠 요청을 문서·기술 시각화·유기적 이미지·publication output으로 연결하는 시스템이라는 정체성과 책임 분리의 이유를 설명할 수 있다.
|
||||
- overview 마지막 문장에서 평가 개발자, capability 기여자, 산출물 리뷰어가 대상임을 바로 확인할 수 있다.
|
||||
5-minutes:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- capabilities와 execution-model에서 핵심 가치와 책임 흐름을, quick-start에서 최소 확인 경로를, architecture에서 구조를, limitations에서 packaging·benchmark·qualification·E2E 한계를 찾을 수 있다.
|
||||
- artifacts에서 버전 관리되는 contract fixture와 ignored 로컬 생성 문서·이미지·기술 시각화를 구분하고 각각의 실제 탐색 경로를 확인할 수 있다.
|
||||
contributor:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- architecture 표에서 capability 구현은 harnesses, 계약과 runtime은 packages, publication adapter는 integrations에서 시작해야 함을 찾을 수 있다.
|
||||
- verification에서 layout test와 전체 unittest discovery 진입점을 확인하고, documentation에서 각 harness README·runtime·E2E·benchmark 정본으로 이동할 수 있다.
|
||||
findings: []
|
||||
@@ -0,0 +1,10 @@
|
||||
# README 품질 검토
|
||||
|
||||
- 판정: **PASS**
|
||||
- 가중 점수: **94/100**
|
||||
- Hard gate: 모두 통과
|
||||
- 독자 시뮬레이션: 30초·5분·기여자 모두 통과
|
||||
|
||||
후보 문서는 Content Harness의 네 capability, contract chain, runtime 소유 경계와 publication 흐름을 저장소 고유 정보로 설명합니다. 체크인된 fixture와 로컬 P6·docvis·이미지 테스트 산출물을 실제 경로로 안내하면서, `runs/**`가 ignored 운영 데이터이며 정본이나 영구 gallery가 아니라는 정책도 명확히 유지합니다.
|
||||
|
||||
명령의 증거 수준도 정직합니다. 다섯 명령의 실제 성공 결과와 전체 suite 명령의 미실행을 분리하고, fixture·layout 검증이 fresh renderer 실행이나 전체 suite를 대신하지 않는다고 밝힙니다. 설치 정본과 version pin 부재로 새 환경의 준비 마찰이 남고 일부 영문 계약 용어가 조밀하지만, 이는 공개된 저장소 한계이며 독자 과업이나 품질 통과를 막지 않습니다.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"run-id": "20260718-rewrite",
|
||||
"repo-id": "image-haness",
|
||||
"mode": "bootstrap",
|
||||
"target-repository": "/home/donghyeon/workspace/ai-tool/image-haness",
|
||||
"harness-version": "0.1.0",
|
||||
"started-at": null,
|
||||
"tool-adapter": "codex",
|
||||
"input-hashes": {}
|
||||
}
|
||||
@@ -0,0 +1,302 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"mode": "bootstrap",
|
||||
"current": "APPLIED",
|
||||
"history": [
|
||||
{
|
||||
"state": "INITIALIZED"
|
||||
},
|
||||
{
|
||||
"state": "INPUT_CAPTURED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "request",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "REPOSITORY_SNAPSHOTTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "snapshot",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"diff-hash": "sha256:d65d7446cad11d46dabd2080c8393059f36fab426f4d62f18183b2c144c3de29"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "FACTS_EXTRACTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "facts",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"fact_ids": [
|
||||
"F-IDENTITY",
|
||||
"F-REPOSITORY-LAYERS",
|
||||
"F-SIBLING-HARNESSES",
|
||||
"F-CAPABILITY-DOCUMENT",
|
||||
"F-CAPABILITY-TECHNICAL",
|
||||
"F-CAPABILITY-IMAGE",
|
||||
"F-ROUTING",
|
||||
"F-CONTRACT-CHAIN",
|
||||
"F-INTEGRATIONS",
|
||||
"F-EXAMPLE-CHAIN",
|
||||
"F-VERSIONED-VISUALS",
|
||||
"F-RUN-WORKSPACE",
|
||||
"F-PORTABLE-OUTPUT",
|
||||
"F-LOCAL-CROSS-HARNESS-OUTPUT",
|
||||
"F-LOCAL-DOCUMENT-VISUALIZATION",
|
||||
"F-LOCAL-IMAGE-OUTPUT",
|
||||
"F-RUNS-NONCANONICAL",
|
||||
"F-PREREQUISITES",
|
||||
"F-NO-PACKAGE-MANIFEST",
|
||||
"F-TEST-INVENTORY",
|
||||
"F-EXECUTED-QUICK-CHECKS",
|
||||
"F-E2E-INPUTS",
|
||||
"F-HYBRID-PENDING",
|
||||
"F-BENCHMARK-MATURITY",
|
||||
"F-NO-GIT-METADATA"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "PROJECT_PROFILED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "profile",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"profile": "generic"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "brief",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
},
|
||||
{
|
||||
"name": "outline",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"section_ids": [
|
||||
"overview",
|
||||
"capabilities",
|
||||
"quick-start",
|
||||
"execution-model",
|
||||
"artifacts",
|
||||
"architecture",
|
||||
"verification",
|
||||
"limitations",
|
||||
"documentation"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_DRAFTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "conformance",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"sections": [
|
||||
"overview",
|
||||
"capabilities",
|
||||
"quick-start",
|
||||
"execution-model",
|
||||
"artifacts",
|
||||
"architecture",
|
||||
"verification",
|
||||
"limitations",
|
||||
"documentation"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "claim_map",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"claims": [
|
||||
"C-IDENTITY",
|
||||
"C-SIBLING-MODEL",
|
||||
"C-DOCUMENT-CAPABILITY",
|
||||
"C-TECHNICAL-CAPABILITY",
|
||||
"C-IMAGE-CAPABILITY",
|
||||
"C-RUNTIME-CAPABILITY",
|
||||
"C-INTEGRATIONS",
|
||||
"C-PREREQUISITES",
|
||||
"C-INSTALLATION-LIMIT",
|
||||
"C-CMD-CONTENT-JOB",
|
||||
"C-RESULT-CONTENT-JOB",
|
||||
"C-CMD-FRONT-DOOR",
|
||||
"C-RESULT-FRONT-DOOR",
|
||||
"C-CONTRACT-CHAIN",
|
||||
"C-ROUTING",
|
||||
"C-RUNTIME-OWNERSHIP",
|
||||
"C-ACCEPTANCE-BOUNDARY",
|
||||
"C-FLOW-VISUAL",
|
||||
"C-VERSIONED-FIXTURE",
|
||||
"C-LOCAL-P6-OUTPUT",
|
||||
"C-LOCAL-DOCVIS-OUTPUT",
|
||||
"C-LOCAL-IMAGE-OUTPUT",
|
||||
"C-RUNS-POLICY",
|
||||
"C-ASSET-PROMOTION",
|
||||
"C-LAYER-OWNERSHIP",
|
||||
"C-DEPENDENCY-DIRECTION",
|
||||
"C-CMD-CONTENT-MANIFEST",
|
||||
"C-RESULT-CONTENT-MANIFEST",
|
||||
"C-CMD-ARTIFACT-SET",
|
||||
"C-RESULT-ARTIFACT-SET",
|
||||
"C-CMD-LAYOUT-TEST",
|
||||
"C-RESULT-LAYOUT-TEST",
|
||||
"C-CMD-FULL-SUITE",
|
||||
"C-FULL-SUITE-SCOPE",
|
||||
"C-E2E-PREREQUISITES",
|
||||
"C-LIMIT-PACKAGING",
|
||||
"C-LIMIT-RUNS",
|
||||
"C-LIMIT-BENCHMARKS",
|
||||
"C-LIMIT-HYBRID",
|
||||
"C-LIMIT-E2E",
|
||||
"C-DOCUMENTATION-MAP"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "VISUALS_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "visual_plan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"visuals": [
|
||||
"content-flow"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "STRUCTURALLY_VALIDATED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "github_markdown",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "TECHNICALLY_VERIFIED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "verify",
|
||||
"ok": true,
|
||||
"warnings": [
|
||||
"manual verification required: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest tests.conformance.test_repository_layout (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest discover -s tests -p 'test_*.py' (unsupported-static-verifier)"
|
||||
],
|
||||
"data": {
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 6,
|
||||
"verified": 0,
|
||||
"manual-required": 6,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 20,
|
||||
"verified": 20,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest tests.conformance.test_repository_layout (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest discover -s tests -p 'test_*.py' (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "secret_scan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "QUALITY_REVIEWED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "review",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"verdict": "PASS",
|
||||
"score": 94,
|
||||
"findings": []
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "READY_FOR_APPLY",
|
||||
"gates": []
|
||||
},
|
||||
{
|
||||
"state": "APPLIED",
|
||||
"gates": []
|
||||
}
|
||||
],
|
||||
"rework": {
|
||||
"iterations": 0,
|
||||
"findings": {}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 6,
|
||||
"verified": 0,
|
||||
"manual-required": 6,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 20,
|
||||
"verified": 20,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest tests.conformance.test_repository_layout (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest discover -s tests -p 'test_*.py' (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
schema-version: 1
|
||||
visuals:
|
||||
- id: content-flow
|
||||
section: execution-model
|
||||
type: request-flow
|
||||
purpose: 자연어 request와 두 contract entry가 workflow-runtime에서 sibling capability로 분기하고 reviewed publication으로 다시 합류하는 소유 경계를 한 화면에 설명한다.
|
||||
placeholder-text: Mermaid flowchart로 request, runtime routing, 세 sibling harness, hybrid composition, reviewed outputs, publication adapter를 표시한다.
|
||||
must-show:
|
||||
- 자연어 요청과 ContentJobRequest 또는 Visual Request
|
||||
- workflow-runtime의 routing, DAG, freshness 책임
|
||||
- document-writing, technical-visualization, image-generation sibling branch
|
||||
- runtime-owned hybrid composition
|
||||
- reviewed publication draft와 accepted ArtifactSet
|
||||
- frozen publication projection과 Markdown, Slides, HTML adapter
|
||||
relationships:
|
||||
- 자연어 요청 -> ContentJobRequest 또는 Visual Request -> workflow-runtime
|
||||
- workflow-runtime -> document-writing
|
||||
- workflow-runtime -> technical-visualization
|
||||
- workflow-runtime -> image-generation
|
||||
- technical-visualization + image-generation -> runtime-owned hybrid composition
|
||||
- reviewed draft 또는 accepted ArtifactSet -> frozen projection -> publication adapter
|
||||
emphasize:
|
||||
- sibling harness는 서로 직접 호출하지 않음
|
||||
- runtime이 분기와 합류를 모두 소유함
|
||||
- 검토된 결과만 publication projection으로 이동함
|
||||
avoid:
|
||||
- image-generation이 exact technical semantics를 소유하는 것처럼 표현하기
|
||||
- integrations가 route나 content를 다시 선택하는 것처럼 표현하기
|
||||
- 로컬 runs 산출물을 canonical input으로 그리기
|
||||
placement:
|
||||
after-section-id: execution-model
|
||||
accessibility:
|
||||
alt-text: 자연어 요청이 ContentJobRequest 또는 Visual Request로 정규화되고 workflow-runtime에서 문서 작성, 기술 시각화, 이미지 생성으로 분기한 뒤 검토된 draft 또는 ArtifactSet과 publication adapter로 합류하는 흐름
|
||||
production:
|
||||
format: mermaid
|
||||
status: embedded
|
||||
@@ -0,0 +1,214 @@
|
||||
# Content Harness
|
||||
|
||||
<!-- section-id: overview -->
|
||||
|
||||
이 저장소는 자연어로 받은 콘텐츠 요청을 문서, 기술 그림, 이미지로 만드는 파이썬 프로젝트입니다. 세 하네스가 각 결과를 만들고 `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`
|
||||
|
||||
독자, 글의 순서, 근거 연결, 그림이 필요한 위치를 정합니다. 요청 명세, 내용 명세, 서사 계획, 게시 초안, 그림 요청을 만들지만 원문을 덮어쓰거나 렌더러를 고르지는 않습니다. <!-- 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 -->
|
||||
|
||||
파일 계약은 `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["요청 명세"]
|
||||
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 --> P["검토된 게시 자료"]
|
||||
T --> P
|
||||
I --> P
|
||||
H --> P
|
||||
P --> O["Markdown · Slides · HTML"]
|
||||
```
|
||||
|
||||
<!-- visual-id: content-flow -->
|
||||
|
||||
`workflow-runtime`이 세 하네스로 요청을 나누고, 검토를 마친 결과를 게시 자료로 합칩니다. <!-- claim-id: C-FLOW-RELATIONSHIPS -->
|
||||
|
||||
구조 검사만 통과한 결과는 바로 게시하지 않습니다. 문서는 지정된 검토를 마쳐야 하고, 기술 그림과 이미지는 `accepted`이면서 통합 준비 상태여야 합니다. <!-- claim-id: C-ACCEPTANCE-BOUNDARY -->
|
||||
|
||||
## 저장소 구성과 변경 위치
|
||||
|
||||
<!-- section-id: architecture -->
|
||||
|
||||
| 경로 | 맡는 일 | 이럴 때 먼저 확인 |
|
||||
| --- | --- | --- |
|
||||
| `.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 -->
|
||||
|
||||
아래 결과는 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`, 종료 코드 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`, 종료 코드 0입니다. 이 명령은 버전 관리되는 계약 예시를 검사하며 새 그림을 렌더링하지 않습니다. <!-- claim-id: C-RESULT-ARTIFACT-SET -->
|
||||
|
||||
### 저장소 구성
|
||||
|
||||
```bash
|
||||
python3 -m unittest tests.conformance.test_repository_layout
|
||||
```
|
||||
<!-- claim-id: C-CMD-LAYOUT-TEST -->
|
||||
|
||||
구성 검사 18개가 통과했습니다. <!-- claim-id: C-RESULT-LAYOUT-TEST -->
|
||||
|
||||
### 전체 테스트
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
```
|
||||
<!-- claim-id: C-CMD-FULL-SUITE -->
|
||||
|
||||
전체 테스트 300개가 615.249초에 통과했습니다. 외부 자료와 별도 검토 파일을 넣어야 하는 종단 간 작업은 이 결과와 구분해야 합니다. <!-- claim-id: C-RESULT-FULL-SUITE -->
|
||||
|
||||
외부 입력을 준비하는 방법은 [종단 간 작업 안내](tests/end-to-end/README.md)에 있습니다. <!-- claim-id: C-E2E-PREREQUISITES -->
|
||||
|
||||
## 현재 한계
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
|
||||
- **설치 절차:** 패키지 설정 파일과 버전 고정값이 없어 하나의 재현 가능한 설치 명령을 제공하지 못합니다. <!-- 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) — 새 실행 할당, 재개, 결과 게시
|
||||
- [문서 작성 하네스](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)
|
||||
@@ -0,0 +1,214 @@
|
||||
# Content Harness
|
||||
|
||||
<!-- section-id: overview -->
|
||||
|
||||
이 저장소는 자연어로 받은 콘텐츠 요청을 문서, 기술 그림, 이미지로 만드는 파이썬 프로젝트입니다. 세 하네스가 각 결과를 만들고 `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`
|
||||
|
||||
독자, 글의 순서, 근거 연결, 그림이 필요한 위치를 정합니다. 요청 명세, 내용 명세, 서사 계획, 게시 초안, 그림 요청을 만들지만 원문을 덮어쓰거나 렌더러를 고르지는 않습니다. <!-- 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 -->
|
||||
|
||||
파일 계약은 `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["요청 명세"]
|
||||
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 --> P["검토된 게시 자료"]
|
||||
T --> P
|
||||
I --> P
|
||||
H --> P
|
||||
P --> O["Markdown · Slides · HTML"]
|
||||
```
|
||||
|
||||
<!-- visual-id: content-flow -->
|
||||
|
||||
`workflow-runtime`이 세 하네스로 요청을 나누고, 검토를 마친 결과를 게시 자료로 합칩니다. <!-- claim-id: C-FLOW-RELATIONSHIPS -->
|
||||
|
||||
구조 검사만 통과한 결과는 바로 게시하지 않습니다. 문서는 지정된 검토를 마쳐야 하고, 기술 그림과 이미지는 `accepted`이면서 통합 준비 상태여야 합니다. <!-- claim-id: C-ACCEPTANCE-BOUNDARY -->
|
||||
|
||||
## 저장소 구성과 변경 위치
|
||||
|
||||
<!-- section-id: architecture -->
|
||||
|
||||
| 경로 | 맡는 일 | 이럴 때 먼저 확인 |
|
||||
| --- | --- | --- |
|
||||
| `.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 -->
|
||||
|
||||
아래 결과는 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`, 종료 코드 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`, 종료 코드 0입니다. 이 명령은 버전 관리되는 계약 예시를 검사하며 새 그림을 렌더링하지 않습니다. <!-- claim-id: C-RESULT-ARTIFACT-SET -->
|
||||
|
||||
### 저장소 구성
|
||||
|
||||
```bash
|
||||
python3 -m unittest tests.conformance.test_repository_layout
|
||||
```
|
||||
<!-- claim-id: C-CMD-LAYOUT-TEST -->
|
||||
|
||||
구성 검사 18개가 통과했습니다. <!-- claim-id: C-RESULT-LAYOUT-TEST -->
|
||||
|
||||
### 전체 테스트
|
||||
|
||||
```bash
|
||||
python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
```
|
||||
<!-- claim-id: C-CMD-FULL-SUITE -->
|
||||
|
||||
전체 테스트 300개가 615.249초에 통과했습니다. 외부 자료와 별도 검토 파일을 넣어야 하는 종단 간 작업은 이 결과와 구분해야 합니다. <!-- claim-id: C-RESULT-FULL-SUITE -->
|
||||
|
||||
외부 입력을 준비하는 방법은 [종단 간 작업 안내](tests/end-to-end/README.md)에 있습니다. <!-- claim-id: C-E2E-PREREQUISITES -->
|
||||
|
||||
## 현재 한계
|
||||
|
||||
<!-- section-id: limitations -->
|
||||
|
||||
- **설치 절차:** 패키지 설정 파일과 버전 고정값이 없어 하나의 재현 가능한 설치 명령을 제공하지 못합니다. <!-- 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) — 새 실행 할당, 재개, 결과 게시
|
||||
- [문서 작성 하네스](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)
|
||||
@@ -0,0 +1,378 @@
|
||||
--- 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)
|
||||
@@ -0,0 +1,7 @@
|
||||
schema-version: 1
|
||||
mode: bootstrap
|
||||
target-rel: README.md
|
||||
generated-hash: sha256:f1e6ff9c315bbd56e83bf6192e73da50096a54a38c2a987232f82a3ee36a4f86
|
||||
target-before-hash: sha256:bb63802996c738e926449e65ee9319825b4bf4f2ab3379ee31afa85e1d5c3cc4
|
||||
repository-snapshot-hash: sha256:0f6969583accd44093b1df782f287d582dfc24bbebbc56d2adefb1c2381f2854
|
||||
review-score: 94
|
||||
@@ -0,0 +1,239 @@
|
||||
schema-version: 1
|
||||
claims:
|
||||
- id: C-IDENTITY
|
||||
type: factual
|
||||
statement: 이 저장소는 자연어로 받은 콘텐츠 요청을 문서, 기술 그림, 이미지로 만드는 파이썬 프로젝트입니다.
|
||||
section: overview
|
||||
sources: [{fact-id: F-IDENTITY}, {fact-id: F-SIBLING-HARNESSES}]
|
||||
status: supported
|
||||
|
||||
- id: C-SHOWCASE-STATUS
|
||||
type: factual
|
||||
statement: 아래 세 파일은 `p6-all-harness-quality-executable-clean-architecture-20260717` 실행에서 검토와 통합 검증을 통과한 결과입니다.
|
||||
section: showcase
|
||||
sources: [{fact-id: F-README-SHOWCASE}]
|
||||
status: supported
|
||||
|
||||
- id: C-SHOWCASE-PROVENANCE
|
||||
type: factual
|
||||
statement: "[산출물 출처 기록](docs/assets/readme-showcase/provenance.yaml)에는 원본 실행 경로, 파일별 SHA-256 해시, 크기, 검토 상태가 들어 있습니다."
|
||||
section: showcase
|
||||
sources: [{fact-id: F-README-SHOWCASE}]
|
||||
status: supported
|
||||
|
||||
- id: C-PREREQUISITES
|
||||
type: factual
|
||||
statement: 기본 실행에는 `Python 3`, `PyYAML`, `jsonschema`가 필요합니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-PREREQUISITES}]
|
||||
status: supported
|
||||
|
||||
- id: C-INSTALLATION-LIMIT
|
||||
type: factual
|
||||
statement: "`pyproject.toml`, `requirements.txt` 같은 패키지 설정 파일도 없습니다."
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-NO-PACKAGE-MANIFEST}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-CONTENT-JOB
|
||||
type: factual
|
||||
statement: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXAMPLE-CHAIN}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-CONTENT-JOB
|
||||
type: factual
|
||||
statement: 2026-07-19 실행에서는 종료 코드 0으로 끝났습니다.
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-FRONT-DOOR
|
||||
type: factual
|
||||
statement: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXAMPLE-CHAIN}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-FRONT-DOOR
|
||||
type: factual
|
||||
statement: "2026-07-19 실행에서는 종료 코드 0과 `primary_capability: document-writing` 계획을 확인했습니다."
|
||||
section: quick-start
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-DOCUMENT-CAPABILITY
|
||||
type: factual
|
||||
statement: 독자, 글의 순서, 근거 연결, 그림이 필요한 위치를 정합니다.
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-CAPABILITY-DOCUMENT}]
|
||||
status: supported
|
||||
|
||||
- id: C-TECHNICAL-CAPABILITY
|
||||
type: factual
|
||||
statement: 코드와 문서에서 확인한 관계를 의미 모형으로 만들고 D2로 렌더링합니다.
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-CAPABILITY-TECHNICAL}]
|
||||
status: supported
|
||||
|
||||
- id: C-IMAGE-CAPABILITY
|
||||
type: factual
|
||||
statement: 사진, 일러스트, 재질, 분위기처럼 유기적인 래스터 이미지를 만듭니다.
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-CAPABILITY-IMAGE}]
|
||||
status: supported
|
||||
|
||||
- id: C-RUNTIME-CAPABILITY
|
||||
type: factual
|
||||
statement: "`workflow-runtime`은 요청 검사, 분기, 작업 순서, 재시도, 결과 취합을 담당합니다."
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-SIBLING-HARNESSES}, {fact-id: F-RUN-WORKSPACE}]
|
||||
status: supported
|
||||
|
||||
- id: C-INTEGRATIONS
|
||||
type: factual
|
||||
statement: "`Markdown`, `Slides`, `HTML` 어댑터는 작업 실행기가 확정한 게시 자료만 받습니다."
|
||||
section: capabilities
|
||||
sources: [{fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CONTRACT-CHAIN
|
||||
type: factual
|
||||
statement: 파일 계약은 `ContentJobRequest` → `Content Manifest` → `Narrative Plan` → `Visual Request` → `ArtifactSet` → 게시 자료 순서로 이어집니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-CONTRACT-CHAIN}]
|
||||
status: supported
|
||||
|
||||
- id: C-ROUTING
|
||||
type: factual
|
||||
statement: 그림 요청이 기술 관계만 포함하면 `technical-visualization`, 이미지 표현만 포함하면 `image-generation`으로 보냅니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-ROUTING}]
|
||||
status: supported
|
||||
|
||||
- id: C-ACCEPTANCE-BOUNDARY
|
||||
type: factual
|
||||
statement: 구조 검사만 통과한 결과는 바로 게시하지 않습니다.
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-CAPABILITY-DOCUMENT}, {fact-id: F-CAPABILITY-TECHNICAL}, {fact-id: F-CAPABILITY-IMAGE}, {fact-id: F-PORTABLE-OUTPUT}]
|
||||
status: supported
|
||||
|
||||
- id: C-FLOW-RELATIONSHIPS
|
||||
type: factual
|
||||
statement: "`workflow-runtime`이 세 하네스로 요청을 나누고, 검토를 마친 결과를 게시 자료로 합칩니다."
|
||||
section: execution-model
|
||||
sources: [{fact-id: F-SIBLING-HARNESSES}, {fact-id: F-CONTRACT-CHAIN}, {fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-DEPENDENCY-DIRECTION
|
||||
type: factual
|
||||
statement: 정본 의존 방향은 도구 연결부 → 하네스 → 공통 계약입니다.
|
||||
section: architecture
|
||||
sources: [{fact-id: F-REPOSITORY-LAYERS}, {fact-id: F-SIBLING-HARNESSES}, {fact-id: F-INTEGRATIONS}]
|
||||
status: supported
|
||||
|
||||
- id: C-VERIFICATION-DATE
|
||||
type: factual
|
||||
statement: 아래 결과는 2026-07-19에 저장소 루트에서 확인했습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-CONTENT-MANIFEST
|
||||
type: factual
|
||||
statement: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
|
||||
section: verification
|
||||
sources: [{fact-id: F-EXAMPLE-CHAIN}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-CONTENT-MANIFEST
|
||||
type: factual
|
||||
statement: 결과는 `VALID`, 종료 코드 0입니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-ARTIFACT-SET
|
||||
type: factual
|
||||
statement: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERSIONED-VISUALS}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-ARTIFACT-SET
|
||||
type: factual
|
||||
statement: 이 명령은 버전 관리되는 계약 예시를 검사하며 새 그림을 렌더링하지 않습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-VERSIONED-VISUALS}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-LAYOUT-TEST
|
||||
type: factual
|
||||
statement: python3 -m unittest tests.conformance.test_repository_layout
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-LAYOUT-TEST
|
||||
type: factual
|
||||
statement: 구성 검사 18개가 통과했습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-CMD-FULL-SUITE
|
||||
type: factual
|
||||
statement: "python3 -m unittest discover -s tests -p 'test_*.py'"
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-RESULT-FULL-SUITE
|
||||
type: factual
|
||||
statement: 전체 테스트 300개가 615.249초에 통과했습니다.
|
||||
section: verification
|
||||
sources: [{fact-id: F-TEST-INVENTORY}, {fact-id: F-EXECUTED-QUICK-CHECKS}]
|
||||
status: supported
|
||||
|
||||
- id: C-E2E-PREREQUISITES
|
||||
type: factual
|
||||
statement: "외부 입력을 준비하는 방법은 [종단 간 작업 안내](tests/end-to-end/README.md)에 있습니다."
|
||||
section: verification
|
||||
sources: [{fact-id: F-E2E-INPUTS}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-PACKAGING
|
||||
type: factual
|
||||
statement: 패키지 설정 파일과 버전 고정값이 없어 하나의 재현 가능한 설치 명령을 제공하지 못합니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-NO-PACKAGE-MANIFEST}, {fact-id: F-PREREQUISITES}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-RUNS
|
||||
type: factual
|
||||
statement: "`runs/`는 버전 관리 대상이 아닙니다."
|
||||
section: limitations
|
||||
sources: [{fact-id: F-RUNS-NONCANONICAL}, {fact-id: F-README-SHOWCASE}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-E2E
|
||||
type: factual
|
||||
statement: 일부 종단 간 작업에는 외부 Java·Gradle 저장소, 원문, 완료된 전문가 검토 파일이 필요합니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-E2E-INPUTS}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-BENCHMARKS
|
||||
type: factual
|
||||
statement: 문서 작성과 이미지 생성 평가는 자료 구조만 정의돼 있고 결과는 아직 없습니다.
|
||||
section: limitations
|
||||
sources: [{fact-id: F-BENCHMARK-MATURITY}]
|
||||
status: supported
|
||||
|
||||
- id: C-LIMIT-HYBRID
|
||||
type: factual
|
||||
statement: "`d2-svg-layer-compositor`는 자동 검사에 통과했지만 사람 검토가 남아 있어 정식 렌더러로 분류하지 않습니다."
|
||||
section: limitations
|
||||
sources: [{fact-id: F-HYBRID-PENDING}]
|
||||
status: supported
|
||||
@@ -0,0 +1,34 @@
|
||||
schema-version: 1
|
||||
repository: /home/donghyeon/workspace/ai-tool/image-haness
|
||||
executed-at: 2026-07-19
|
||||
working-directory: repository root
|
||||
commands:
|
||||
- id: CMD-001
|
||||
exit-code: 0
|
||||
observed: 출력 없이 완료
|
||||
independently-rechecked: true
|
||||
- id: CMD-002
|
||||
exit-code: 0
|
||||
observed: "primary_capability: document-writing"
|
||||
independently-rechecked: true
|
||||
- id: CMD-003
|
||||
exit-code: 0
|
||||
observed: VALID
|
||||
independently-rechecked: true
|
||||
- id: CMD-004
|
||||
exit-code: 0
|
||||
observed: VALID
|
||||
independently-rechecked: true
|
||||
- id: CMD-005
|
||||
exit-code: 0
|
||||
observed: 18 tests passed
|
||||
independently-rechecked: true
|
||||
- id: CMD-006
|
||||
exit-code: 0
|
||||
observed: 300 tests passed
|
||||
duration-seconds: 615.249
|
||||
independently-rechecked: false
|
||||
limitations:
|
||||
- 독립 실행 검증자는 CMD-001부터 CMD-005까지 다시 실행했다.
|
||||
- CMD-006은 현재 README 작성 세션에서 실행했으며 독립 검증자는 300개 테스트가 존재하는지만 다시 확인했다.
|
||||
- verification.json의 정적 검사 결과와 실제 실행 결과는 서로 다른 검증 수준이다.
|
||||
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"policy-id": "korean-reader-prose-v1",
|
||||
"language": "ko-KR",
|
||||
"applicable": true,
|
||||
"scope": "candidate",
|
||||
"state": "PASS",
|
||||
"summary": {
|
||||
"errors": 0,
|
||||
"warnings": 0,
|
||||
"sentences": 78,
|
||||
"prose-characters": 2023,
|
||||
"hangul-characters": 1775
|
||||
},
|
||||
"findings": []
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
schema-version: 2
|
||||
mode: bootstrap
|
||||
profile: generic
|
||||
repository-snapshot-hash: sha256:0f6969583accd44093b1df782f287d582dfc24bbebbc56d2adefb1c2381f2854
|
||||
artifacts:
|
||||
readme-request.yaml: sha256:8ab945ced2bb7ee124f55c12baa41759a971e5b72267d4f4284b22020281e9a9
|
||||
repository-facts.yaml: sha256:997882f1cdf9e9a69797939fc2db58a3757d027184c70ab67c7133612461979f
|
||||
readme-brief.yaml: sha256:2f60e1fb0f63467b213c5ce483ff88413b9982fcb0841394c3ef3edbb15c14f9
|
||||
readme-outline.yaml: sha256:4d49c2204058ed1b3d8ff0b4f684a704f1c24e386f43cec9c214f47b338a5b66
|
||||
README.candidate.md: sha256:f1e6ff9c315bbd56e83bf6192e73da50096a54a38c2a987232f82a3ee36a4f86
|
||||
claim-map.yaml: sha256:1ba678e33ec7ea25b5d675c5cfbad9b8c3736ac13fdeba62424bddff345fadd5
|
||||
visual-plan.yaml: sha256:1440c3055cede6634bf9adbfe4343631e97e1f21a8ee2ea8f04f5753c2555b79
|
||||
prose-report.json: sha256:bc4f0930ea0996bcf969ff12433d2c7c0f5a9c06796243d06e828e64a2b2772c
|
||||
review-findings.yaml: sha256:fdd3180866eb42edf14162e2160b54dfd382c44ea280880744356424a5428fec
|
||||
@@ -0,0 +1,51 @@
|
||||
schema-version: 1
|
||||
project-profile:
|
||||
primary: generic
|
||||
secondary:
|
||||
- 여러 종류의 콘텐츠를 만드는 작업 흐름
|
||||
- 파일 계약으로 연결된 Python 시스템
|
||||
audiences:
|
||||
primary:
|
||||
- 콘텐츠 하네스가 만드는 결과와 실행 방법을 확인하려는 개발자
|
||||
- 문서 작성, 기술 시각화, 이미지 생성 기능을 수정하려는 개발자
|
||||
secondary:
|
||||
- 산출물의 근거와 검토 절차를 확인하려는 기술 책임자
|
||||
reader-outcomes:
|
||||
- 검토를 통과한 문서, 이미지, 기술 시각화 결과를 바로 확인한다.
|
||||
- 예제 요청을 검사하고 전체 테스트를 실행할 수 있다.
|
||||
- 네 기능의 책임과 서로 직접 호출하지 않는 경계를 설명할 수 있다.
|
||||
- 변경하려는 기능의 정본 경로를 찾을 수 있다.
|
||||
- 실행 기록, 버전 관리되는 예시, 아직 끝나지 않은 검증을 구분한다.
|
||||
project-story:
|
||||
value-proposition: 자연어 요청을 문서, 기술 그림, 이미지로 만들고 검토가 끝난 결과만 게시 파일로 묶는다.
|
||||
problem: 결과 종류마다 생성 방법과 검토 기준이 다르므로, 한 작업 흐름으로 연결하되 각 기능의 책임은 섞이지 않아야 한다.
|
||||
target-reader: 저장소를 평가하거나 기능을 수정하려는 개발자
|
||||
notable-traits:
|
||||
- text: 문서 작성, 기술 시각화, 이미지 생성은 서로 직접 호출하지 않으며 작업 실행기가 분기와 결과 조립을 맡는다.
|
||||
fact-ids: [F-SIBLING-HARNESSES, F-ROUTING]
|
||||
- text: 검토를 통과한 대표 산출물 세 개를 영구 문서 경로에서 바로 볼 수 있다.
|
||||
fact-ids: [F-README-SHOWCASE]
|
||||
- text: 요청부터 게시 파일까지 단계마다 별도 계약을 사용한다.
|
||||
fact-ids: [F-CONTRACT-CHAIN, F-INTEGRATIONS]
|
||||
- text: 새 실행은 기존 결과를 덮어쓰지 않고 별도 작업공간을 만든다.
|
||||
fact-ids: [F-RUN-WORKSPACE]
|
||||
maturity: 핵심 계약과 네 기능, 통합 어댑터, 300개 테스트가 구현돼 있다. 일부 평가 자료와 혼합 합성기의 사람 검토는 아직 끝나지 않았다.
|
||||
limitations:
|
||||
- 의존성 버전과 설치 절차를 고정하는 패키지 설정 파일이 없다.
|
||||
- 외부 자료와 별도 전문가 검토가 필요한 종단 간 실행이 있다.
|
||||
- runs 아래 파일은 실행 기록이며 재사용할 예시는 docs 또는 examples로 옮겨야 한다.
|
||||
- d2-svg-layer-compositor는 자동 검사를 통과했지만 사람 검토가 남았다.
|
||||
narrative-variant: product
|
||||
reader-journey:
|
||||
- reader-question: 이 저장소로 만든 결과를 먼저 볼 수 있는가?
|
||||
section-id: showcase
|
||||
- reader-question: 가장 짧게 동작을 확인하려면 무엇을 실행하는가?
|
||||
section-id: quick-start
|
||||
- reader-question: 각 기능은 무엇을 맡고 어디까지 책임지는가?
|
||||
section-id: capabilities
|
||||
- reader-question: 요청은 어떤 단계를 거쳐 게시 파일이 되는가?
|
||||
section-id: execution-model
|
||||
- reader-question: 기능을 고치려면 어느 디렉터리부터 봐야 하는가?
|
||||
section-id: architecture
|
||||
- reader-question: 현재 통과한 검사와 남아 있는 한계는 무엇인가?
|
||||
section-id: verification
|
||||
@@ -0,0 +1,141 @@
|
||||
schema-version: 1
|
||||
sections:
|
||||
- id: overview
|
||||
title-guidance: Content Harness
|
||||
level: 1
|
||||
purpose: 무엇을 만드는 저장소인지 두 문장 안에 밝힌다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 만드는 결과와 작업 실행기의 역할
|
||||
- 이 문서가 도움 되는 독자
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 별도 표지 그림이 첫 설명보다 필요한가?
|
||||
rationale: 바로 아래 대표 산출물이 실제 결과를 보여 주므로 장식 그림은 넣지 않는다.
|
||||
|
||||
- id: showcase
|
||||
title-guidance: 검토를 마친 결과 예시
|
||||
level: 2
|
||||
purpose: 검토 완료된 이미지, 기술 그림, 통합 문서를 README 안에서 보여 준다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 이미지 생성 결과와 무엇을 판단할 수 있는지 설명
|
||||
- 기술 시각화 결과와 무엇을 판단할 수 있는지 설명
|
||||
- 세 기능을 합친 문서 미리보기
|
||||
- 출처 실행, 검토 상태, 해시를 기록한 provenance 링크
|
||||
visual-slot:
|
||||
decision: include
|
||||
reader-question: 실제로 어떤 결과를 만드는지 바로 확인할 수 있는가?
|
||||
rationale: 결과물 자체를 보는 것이 기능 이름을 나열하는 것보다 빠르고 정확하다.
|
||||
purpose: 검토 완료 산출물 세 개를 역할과 함께 보여 준다.
|
||||
|
||||
- id: quick-start
|
||||
title-guidance: 먼저 실행해 보기
|
||||
level: 2
|
||||
purpose: 준비 사항과 가장 짧은 예제 검증 경로를 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- Python과 선택 도구
|
||||
- 정본 설치 명령이 없는 이유
|
||||
- 요청 검사와 작업 계획 명령
|
||||
- 실제 확인한 성공 결과와 범위
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 두 명령을 실행하는 데 그림이 필요한가?
|
||||
rationale: 복사할 수 있는 명령과 성공 신호만 두는 편이 빠르다.
|
||||
|
||||
- id: capabilities
|
||||
title-guidance: 기능별 책임
|
||||
level: 2
|
||||
purpose: 네 기능이 맡는 일과 하지 않는 일을 구분한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 문서 작성
|
||||
- 기술 시각화
|
||||
- 이미지 생성
|
||||
- 작업 실행기와 통합 어댑터
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 책임을 비교할 때 별도 그림이 필요한가?
|
||||
rationale: 짧은 소제목과 경계 설명이 경로를 찾는 데 더 정확하다.
|
||||
|
||||
- id: execution-model
|
||||
title-guidance: 요청이 결과가 되는 과정
|
||||
level: 2
|
||||
purpose: 계약 순서, 분기, 검토, 게시 파일 생성을 한 흐름으로 설명한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 계약 사슬
|
||||
- 기술 그림과 이미지 분기 규칙
|
||||
- 검토를 통과한 결과만 합치는 경계
|
||||
visual-slot:
|
||||
decision: include
|
||||
reader-question: 세 기능이 어디서 갈라지고 합쳐지는가?
|
||||
rationale: 분기와 합류가 함께 있어 작은 흐름도가 문장보다 빠르다.
|
||||
purpose: 작업 실행기가 세 기능을 나누고 결과를 합치는 과정을 보여 준다.
|
||||
|
||||
- id: architecture
|
||||
title-guidance: 저장소 구성과 변경 위치
|
||||
level: 2
|
||||
purpose: 수정 목적에 따라 시작할 디렉터리를 안내한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 주요 디렉터리의 정본 책임
|
||||
- 어댑터, 하네스, 계약의 의존 방향
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 파일 경로를 찾는 데 그림이 표보다 나은가?
|
||||
rationale: 경로와 책임을 짝지은 표가 바로 이동하기 쉽다.
|
||||
|
||||
- id: verification
|
||||
title-guidance: 검증
|
||||
level: 2
|
||||
purpose: 이번 작업에서 실행한 검사와 성공 신호를 적는다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 콘텐츠 명세 검사
|
||||
- 산출물 묶음 검사
|
||||
- 저장소 구성 검사
|
||||
- 전체 300개 테스트 결과
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 검사 결과를 이해하는 데 그림이 필요한가?
|
||||
rationale: 명령과 성공 결과를 바로 붙이는 편이 재현하기 쉽다.
|
||||
|
||||
- id: limitations
|
||||
title-guidance: 현재 한계
|
||||
level: 2
|
||||
purpose: 설치, 실행 기록, 외부 입력, 아직 끝나지 않은 평가를 밝힌다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 패키지 설정 파일 부재
|
||||
- runs의 비영속성
|
||||
- 외부 입력이 필요한 종단 간 실행
|
||||
- 평가 자료와 사람 검토 상태
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 남은 제약을 이해하는 데 그림이 필요한가?
|
||||
rationale: 영향과 후속 행동을 붙인 짧은 목록이면 충분하다.
|
||||
|
||||
- id: documentation
|
||||
title-guidance: 더 읽을 문서
|
||||
level: 2
|
||||
purpose: 설계와 기능별 상세 문서로 이동하는 링크를 제공한다.
|
||||
required: true
|
||||
content-strategy: inline
|
||||
content-requirements:
|
||||
- 전체 설계
|
||||
- 문서 색인과 실행 작업공간 정책
|
||||
- 기능별 안내서와 종단 간 예제
|
||||
visual-slot:
|
||||
decision: exclude
|
||||
reader-question: 세부 문서를 찾는 데 그림이 필요한가?
|
||||
rationale: 목적을 붙인 상대 링크 목록이 가장 빠르다.
|
||||
@@ -0,0 +1,56 @@
|
||||
schema-version: 1
|
||||
target:
|
||||
repository: /home/donghyeon/workspace/ai-tool/image-haness
|
||||
readme-path: README.md
|
||||
mode: bootstrap
|
||||
profile-override: generic
|
||||
project-intent:
|
||||
purpose: 저장소가 만드는 문서·기술 그림·이미지를 먼저 보여 주고, 각 기능의 책임과 실행 방법을 실제 구현과 검증 결과에 근거해 설명한다.
|
||||
positioning: 콘텐츠 하네스를 처음 살펴보는 개발자와 기능을 수정하려는 기여자가 필요한 정보를 빠르게 찾는 저장소 안내서다.
|
||||
maturity: 검토를 통과한 대표 산출물, 현재 구현, 실행한 테스트, 아직 끝나지 않은 검증을 서로 구분해 적는다.
|
||||
audience:
|
||||
primary:
|
||||
- 콘텐츠 하네스가 무엇을 만들고 어떻게 확인하는지 알고 싶은 개발자
|
||||
- 문서 작성, 기술 시각화, 이미지 생성 흐름을 수정하려는 개발자
|
||||
secondary:
|
||||
- 생성 문서와 시각 산출물의 계약·검증 방식을 검토하는 기술 리더
|
||||
reader-actions:
|
||||
- 검토를 통과한 문서, 이미지, 기술 시각화 결과를 바로 확인한다.
|
||||
- 가장 짧은 예제 명령과 전체 테스트 명령을 실행한다.
|
||||
- 각 기능이 맡는 일과 수정할 디렉터리를 찾는다.
|
||||
- 실행 기록과 버전 관리되는 예시를 구분한다.
|
||||
- 필요한 도구와 아직 끝나지 않은 검증을 확인한다.
|
||||
content-policy:
|
||||
language: ko-KR
|
||||
tone: 결론을 먼저 말하는 짧고 자연스러운 한국어. 제품명과 코드 식별자는 인라인 코드로 보존하고 일반 개념은 익숙한 한국어로 설명한다.
|
||||
target-length: medium
|
||||
preserve-existing-copy: false
|
||||
detail-docs-policy: summary-and-link
|
||||
visual-policy:
|
||||
mode: when-useful
|
||||
max-visuals: 4
|
||||
preferred-formats:
|
||||
- repository-owned raster or SVG artifact
|
||||
- mermaid
|
||||
placeholder-format: HTML 주석 기반 제작 사양; 검증된 기존 산출물은 저장소 상대 경로로 직접 표시
|
||||
must-include:
|
||||
- 프로젝트 개요와 대상 독자
|
||||
- 검토 완료된 이미지 생성, 기술 시각화, 통합 문서 산출물 3종과 출처 기록
|
||||
- document-writing, technical-visualization, image-generation, workflow-runtime의 책임과 연결 관계
|
||||
- 대표 검증 또는 실행 흐름과 명령별 검증 수준
|
||||
- 테스트로 생성된 이미지, 문서, 기술 시각화 산출물의 실제 경로와 성격
|
||||
- 저장소 구조와 기여 위치
|
||||
- 필수 및 선택 도구
|
||||
- runs 디렉터리의 실행 기록 성격과 정본으로 사용하지 않는다는 경계
|
||||
- 현재 구현 상태와 확인된 한계
|
||||
- ARCHITECTURE.md와 docs 색인 링크
|
||||
must-exclude:
|
||||
- 저장소 근거가 없는 기능·버전·성능·품질 우위 주장
|
||||
- 실패·중간 후보 산출물을 성공 예시로 오인시키는 표현
|
||||
- 비밀 값 또는 개인 환경의 절대 경로
|
||||
- 상세 설계 이력과 모든 run 파일의 장문 나열
|
||||
- 일반 개념을 불필요하게 영어로 나열하는 제목과 설명
|
||||
- 작성 과정이나 문서 자체를 설명하는 메타 문장
|
||||
- 독자의 행동과 관계없는 수식어, 반복 요약, 장식용 문구
|
||||
- runs 경로의 파일을 README에 직접 삽입하는 링크
|
||||
protected-sections: []
|
||||
@@ -0,0 +1,615 @@
|
||||
schema-version: 1
|
||||
repository-snapshot-hash: sha256:0f6969583accd44093b1df782f287d582dfc24bbebbc56d2adefb1c2381f2854
|
||||
project-name: Content Harness
|
||||
languages: [Python, YAML, JSON, Markdown]
|
||||
facts:
|
||||
- id: F-IDENTITY
|
||||
category: identity
|
||||
key: project-purpose
|
||||
value:
|
||||
name: Content Harness
|
||||
purpose: provider-neutral technical-document planning, exact technical visualization, organic image generation, and accepted-asset publication
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: README.md
|
||||
line-start: 1
|
||||
line-end: 14
|
||||
source-kind: project-documentation
|
||||
- path: packages/workflow-runtime/handlers.yaml
|
||||
line-start: 1
|
||||
line-end: 8
|
||||
source-kind: handler-registry
|
||||
|
||||
- id: F-REPOSITORY-LAYERS
|
||||
category: architecture
|
||||
key: canonical-layer-ownership
|
||||
value:
|
||||
.agents-and-.codex: thin provider discovery adapters
|
||||
harnesses: capability policy and implementation canon
|
||||
packages: contracts and runtime canon
|
||||
integrations: publication target adapters
|
||||
tests: repository-wide validation and golden artifacts
|
||||
examples: versioned executable examples
|
||||
benchmarks: evaluation suites and failure corpora
|
||||
runs: ignored local workflow data
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 3
|
||||
line-end: 28
|
||||
source-kind: architecture-documentation
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 55
|
||||
line-end: 67
|
||||
source-kind: architecture-documentation
|
||||
- path: .codex/agents/natural-prose-reviewer.toml
|
||||
line-start: 1
|
||||
line-end: 9
|
||||
source-kind: thin-provider-adapter
|
||||
|
||||
- id: F-SIBLING-HARNESSES
|
||||
category: architecture
|
||||
key: sibling-harness-runtime-boundary
|
||||
value:
|
||||
handlers: [document-writing, technical-visualization, image-generation]
|
||||
rule: sibling harnesses return plans or results and do not call one another
|
||||
runtime-responsibility: validation, routing, DAG execution, retries, result transfer, integration, and events
|
||||
execution-boundary: workflow-runtime -> handlers.yaml -> HarnessHandler -> immutable JobResult
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 30
|
||||
line-end: 53
|
||||
source-kind: architecture-documentation
|
||||
- path: packages/workflow-runtime/handlers.yaml
|
||||
line-start: 1
|
||||
line-end: 8
|
||||
source-kind: handler-registry
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
line-start: 43
|
||||
line-end: 51
|
||||
source-kind: conformance-test
|
||||
|
||||
- id: F-CAPABILITY-DOCUMENT
|
||||
category: capability
|
||||
key: document-writing
|
||||
value:
|
||||
owns: [narrative, audience, evidence linkage, visual-opportunity detection, figure context]
|
||||
operations: [document-writing.intake, document-writing.analyze, document-writing.plan, document-writing.revise, document-writing.draft]
|
||||
outputs: [content-job-request, publication-draft, content-manifest, narrative-plan, narrative-analysis, reviews, visual-requests]
|
||||
boundary: never edits the source document in place and does not select renderers or generate imagery
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: harnesses/document-writing/README.md
|
||||
line-start: 3
|
||||
line-end: 29
|
||||
source-kind: capability-documentation
|
||||
- path: harnesses/document-writing/capability.yaml
|
||||
line-start: 1
|
||||
line-end: 22
|
||||
source-kind: capability-declaration
|
||||
- path: harnesses/document-writing/handler.py
|
||||
line-start: 253
|
||||
line-end: 345
|
||||
symbol: DocumentWritingHandler
|
||||
source-kind: implementation
|
||||
|
||||
- id: F-CAPABILITY-TECHNICAL
|
||||
category: capability
|
||||
key: technical-visualization
|
||||
value:
|
||||
owns: [evidence-grounded semantic models, visual grammar, deterministic rendering, target-specific renditions]
|
||||
executable-visual-types: [dependency-graph, runtime-sequence]
|
||||
renderer: d2
|
||||
output-profiles: [document, presentation]
|
||||
acceptance-boundary: separate exact-input technical-semantic and technical-visual expert reviews are required
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: harnesses/technical-visualization/README.md
|
||||
line-start: 3
|
||||
line-end: 23
|
||||
source-kind: capability-documentation
|
||||
- path: harnesses/technical-visualization/capability.yaml
|
||||
line-start: 1
|
||||
line-end: 23
|
||||
source-kind: capability-declaration
|
||||
- path: harnesses/technical-visualization/handler.py
|
||||
line-start: 904
|
||||
line-end: 962
|
||||
symbol: TechnicalVisualizationHandler
|
||||
source-kind: implementation
|
||||
|
||||
- id: F-CAPABILITY-IMAGE
|
||||
category: capability
|
||||
key: image-generation
|
||||
value:
|
||||
owns: [organic raster imagery, photography, illustration, bounded candidate search, local repair]
|
||||
operations: [image-generation.generate, image-generation.generate-component]
|
||||
production-model: three hashed candidates, pairwise comparison, explicit selection, and at most one bounded repair
|
||||
excluded: [exact architecture relations, charts, state transitions, long exact text, evidence-derived technical geometry]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: harnesses/image-generation/README.md
|
||||
line-start: 3
|
||||
line-end: 26
|
||||
source-kind: capability-documentation
|
||||
- path: harnesses/image-generation/capability.yaml
|
||||
line-start: 1
|
||||
line-end: 24
|
||||
source-kind: capability-declaration
|
||||
- path: harnesses/image-generation/handler.py
|
||||
line-start: 246
|
||||
line-end: 301
|
||||
symbol: ImageGenerationHandler
|
||||
source-kind: implementation
|
||||
|
||||
- id: F-ROUTING
|
||||
category: architecture
|
||||
key: visual-routing-policy
|
||||
value:
|
||||
technical-only: technical-visualization
|
||||
image-only: image-generation
|
||||
both: hybrid DAG
|
||||
neither: BLOCKED_UNRESOLVED
|
||||
explicit-conflict: ROUTING_CONFLICT
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 100
|
||||
line-end: 118
|
||||
source-kind: architecture-documentation
|
||||
- path: packages/workflow-runtime/policies/routing.yaml
|
||||
line-start: 27
|
||||
line-end: 31
|
||||
source-kind: runtime-policy
|
||||
|
||||
- id: F-CONTRACT-CHAIN
|
||||
category: architecture
|
||||
key: content-to-publication-contract-chain
|
||||
value:
|
||||
- ContentJobRequest
|
||||
- Content Manifest
|
||||
- Narrative Plan
|
||||
- Visual Request
|
||||
- ArtifactSet
|
||||
- frozen publication projection
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: ARCHITECTURE.md
|
||||
line-start: 69
|
||||
line-end: 98
|
||||
source-kind: architecture-documentation
|
||||
|
||||
- id: F-INTEGRATIONS
|
||||
category: capability
|
||||
key: publication-adapters
|
||||
value:
|
||||
targets: [Markdown, Slides, HTML]
|
||||
input: one runtime-selected frozen publication projection
|
||||
boundary: adapters do not choose content, route, renderer, provider, or visual grammar
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: integrations/README.md
|
||||
line-start: 1
|
||||
line-end: 11
|
||||
source-kind: integration-documentation
|
||||
|
||||
- id: F-EXAMPLE-CHAIN
|
||||
category: examples
|
||||
key: checked-in-clean-architecture-chain
|
||||
value:
|
||||
root: examples/clean-architecture
|
||||
contracts: [content-job-request.yaml, content-manifest.yaml, narrative-plan.yaml, reference-registry.yaml, visual-request.yaml, workflow-request.content-job.yaml, workflow-request.visual.yaml, artifact/attempt-01/artifact-set.yaml]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
line-start: 480
|
||||
line-end: 496
|
||||
source-kind: conformance-test
|
||||
- path: examples/clean-architecture/content-job-request.yaml
|
||||
source-kind: versioned-example
|
||||
|
||||
- id: F-VERSIONED-VISUALS
|
||||
category: artifacts
|
||||
key: checked-in-technical-visual-contract-fixture
|
||||
value:
|
||||
artifact-status: accepted
|
||||
integration-status: ready
|
||||
scope: contract-only fixture rather than renderer-backed golden comparison
|
||||
renditions:
|
||||
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.svg, target: document, dimensions: 820x460}
|
||||
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation.svg, target: presentation, dimensions: 1600x900}
|
||||
- {path: examples/clean-architecture/artifact/attempt-01/dependency-directions.presentation-step-1.svg, target: presentation-reveal-step, dimensions: 1600x900}
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: examples/clean-architecture/artifact/attempt-01/artifact-set.yaml
|
||||
line-start: 2
|
||||
line-end: 78
|
||||
source-kind: artifact-manifest
|
||||
- path: tests/golden/dependency-directions/README.md
|
||||
line-start: 1
|
||||
line-end: 7
|
||||
source-kind: golden-fixture-documentation
|
||||
|
||||
- id: F-RUN-WORKSPACE
|
||||
category: runtime
|
||||
key: fresh-run-allocation
|
||||
value:
|
||||
path: runs/<purpose>/run-<YYYYMMDDTHHMMSSZ>-NNN/
|
||||
semantics: each valid fresh intake or execution creates a new immutable workspace; matching request or workflow ids do not authorize reuse
|
||||
optional-output: <run-root>/output/
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/README.md
|
||||
line-start: 1
|
||||
line-end: 32
|
||||
source-kind: runtime-workspace-policy
|
||||
- path: packages/workflow-runtime/README.md
|
||||
line-start: 86
|
||||
line-end: 98
|
||||
source-kind: runtime-documentation
|
||||
|
||||
- id: F-PORTABLE-OUTPUT
|
||||
category: artifacts
|
||||
key: reviewed-output-bundle
|
||||
value:
|
||||
location: <run-root>/output/
|
||||
entrypoint: index.html
|
||||
manifest: manifest.yaml
|
||||
condition: reviewed publication draft or accepted integration-ready ArtifactSet
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: packages/workflow-runtime/README.md
|
||||
line-start: 216
|
||||
line-end: 221
|
||||
source-kind: runtime-documentation
|
||||
- path: tests/runtime/test_output_bundle.py
|
||||
line-start: 176
|
||||
line-end: 204
|
||||
symbol: test_bundle_is_portable_and_manifest_hashes_match
|
||||
source-kind: runtime-test
|
||||
|
||||
- id: F-LOCAL-CROSS-HARNESS-OUTPUT
|
||||
category: artifacts
|
||||
key: local-cross-harness-test-output
|
||||
value:
|
||||
root: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output
|
||||
generated-document: [README.md, final-document.md, index.html, preview.png]
|
||||
technical-visualization: [assets/dependency-directions.document.svg, assets/dependency-directions.presentation.svg]
|
||||
image-generation: [assets/editorial-workbench.document.png, assets/editorial-workbench.presentation.png, assets/image-candidates.png]
|
||||
validation: validation-summary.yaml
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/manifest.yaml
|
||||
line-start: 1
|
||||
line-end: 35
|
||||
source-kind: local-generated-output-manifest
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/README.md
|
||||
line-start: 1
|
||||
line-end: 12
|
||||
source-kind: local-generated-document
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/preview.png
|
||||
source-kind: local-generated-preview
|
||||
|
||||
- id: F-LOCAL-DOCUMENT-VISUALIZATION
|
||||
category: artifacts
|
||||
key: local-document-visualization-test-output
|
||||
value:
|
||||
root: runs/docvis-20260716-executable-clean-architecture-part1
|
||||
document-output: document/part1-integrated.html
|
||||
figures: [fig-invisible-shortcut, fig-enforcement-gradient]
|
||||
formats: [desktop-SVG, mobile-SVG, PNG-fallback]
|
||||
previews: [integrated-previews/part1-desktop.png, integrated-previews/part1-mobile-v2.png]
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/docvis-20260716-executable-clean-architecture-part1/delivery/delivery-manifest.yaml
|
||||
line-start: 1
|
||||
line-end: 24
|
||||
source-kind: local-delivery-manifest
|
||||
- path: runs/docvis-20260716-executable-clean-architecture-part1/figures/fig-enforcement-gradient/asset-manifest.yaml
|
||||
line-start: 1
|
||||
line-end: 30
|
||||
source-kind: local-figure-manifest
|
||||
|
||||
- id: F-LOCAL-IMAGE-OUTPUT
|
||||
category: artifacts
|
||||
key: local-best-of-three-image-test-output
|
||||
value:
|
||||
root: runs/img-20260716-japanese-animation-test
|
||||
generation-candidates: 3
|
||||
selected-attempt: 2
|
||||
selected-output: outputs/final-selected.png
|
||||
selection-label: BEST_OF_N_PASS
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: runs/img-20260716-japanese-animation-test/selection.json
|
||||
line-start: 1
|
||||
line-end: 64
|
||||
source-kind: local-selection-record
|
||||
- path: runs/img-20260716-japanese-animation-test/outputs/final-selected.png
|
||||
source-kind: local-generated-image
|
||||
|
||||
- id: F-README-SHOWCASE
|
||||
category: artifacts
|
||||
key: reviewed-readme-showcase
|
||||
value:
|
||||
source-run: p6-all-harness-quality-executable-clean-architecture-20260717
|
||||
source-status: PASS
|
||||
promotion-policy: 검토 완료 출력만 runs에서 docs/assets/readme-showcase로 복사
|
||||
assets:
|
||||
- {path: docs/assets/readme-showcase/editorial-workbench.png, role: 이미지 생성 결과, dimensions: 1200x675, sha256: aaf6a848e5a1094c6620fa2545df6e9e156b2af136d7bf7486840be93fcb10f1}
|
||||
- {path: docs/assets/readme-showcase/dependency-directions.svg, role: 기술 시각화 결과, dimensions: 1600x900, sha256: 5dacb86fb637bf0ac3ae6bf6cd9f97ea1fbc7112c02edc859ef1574cc55226cf}
|
||||
- {path: docs/assets/readme-showcase/publication-preview.png, role: 통합 문서 결과, dimensions: 1440x2400, sha256: a12aaf738c3e4c4773666d96ba46f8e341065407e975c34a69a50d390102d979}
|
||||
provenance: docs/assets/readme-showcase/provenance.yaml
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: docs/assets/readme-showcase/provenance.yaml
|
||||
line-start: 1
|
||||
line-end: 28
|
||||
source-kind: promoted-artifact-provenance
|
||||
- path: runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/validation-summary.yaml
|
||||
line-start: 1
|
||||
line-end: 145
|
||||
source-kind: local-validation-summary
|
||||
|
||||
- id: F-RUNS-NONCANONICAL
|
||||
category: limitation
|
||||
key: local-run-durability
|
||||
value: runs/** is ignored local operational data, not a cache or source of truth; reusable examples belong under examples, regression oracles under tests/golden, and evaluation corpora under benchmarks
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .gitignore
|
||||
line-start: 5
|
||||
line-end: 7
|
||||
source-kind: ignore-policy
|
||||
- path: runs/README.md
|
||||
line-start: 1
|
||||
line-end: 7
|
||||
source-kind: runtime-workspace-policy
|
||||
- path: docs/README.md
|
||||
line-start: 23
|
||||
line-end: 35
|
||||
source-kind: documentation-policy
|
||||
|
||||
- id: F-PREREQUISITES
|
||||
category: prerequisites
|
||||
key: runtime-tools
|
||||
value:
|
||||
language: Python 3
|
||||
python-packages: [PyYAML, jsonschema, Pillow]
|
||||
feature-specific-tools:
|
||||
technical-rendering: D2
|
||||
SVG-preview: Chrome or Chromium
|
||||
version-pins: not declared
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: README.md
|
||||
line-start: 151
|
||||
line-end: 153
|
||||
source-kind: project-documentation
|
||||
- path: packages/schema-support/src/contract_support.py
|
||||
line-start: 13
|
||||
line-end: 14
|
||||
source-kind: dependency-import
|
||||
- path: packages/export-validator/src/validate_export.py
|
||||
line-start: 1
|
||||
line-end: 14
|
||||
source-kind: dependency-import
|
||||
- path: harnesses/technical-visualization/renderers/d2/renderer.py
|
||||
line-start: 206
|
||||
line-end: 213
|
||||
source-kind: renderer-implementation
|
||||
- path: harnesses/image-generation/scripts/render_svg_preview.py
|
||||
line-start: 18
|
||||
line-end: 31
|
||||
source-kind: preview-implementation
|
||||
|
||||
- id: F-NO-PACKAGE-MANIFEST
|
||||
category: limitation
|
||||
key: dependency-installation-metadata
|
||||
value: no pyproject.toml, requirements.txt, setup.py, setup.cfg, Pipfile, poetry.lock, or uv.lock is present; dependency versions and one canonical installation command cannot be evidenced
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .
|
||||
source-kind: repository-file-scan
|
||||
|
||||
- id: F-TEST-INVENTORY
|
||||
category: tests
|
||||
key: unittest-suite
|
||||
value:
|
||||
framework: unittest
|
||||
observed-test-methods: 300
|
||||
groups: [conformance, contracts, failure_injection, harnesses, integrations, runtime]
|
||||
declared-latest-full-run: 300 tests passed in repository refactoring review
|
||||
current-readme-run-check: repository-layout module passed 18 tests
|
||||
current-readme-full-run: 300 tests passed
|
||||
assertion-type: derived
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: tests
|
||||
source-kind: test-directory-scan
|
||||
- path: docs/refactoring-review.md
|
||||
line-start: 76
|
||||
line-end: 91
|
||||
source-kind: declared-verification-report
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
source-kind: executed-test-module
|
||||
|
||||
- id: F-EXECUTED-QUICK-CHECKS
|
||||
category: verification
|
||||
key: readme-authoring-session-executions
|
||||
value:
|
||||
date: 2026-07-19
|
||||
content-job-request-validation: {exit-code: 0}
|
||||
content-manifest-validation: {exit-code: 0, output: VALID}
|
||||
front-door-content-plan: {exit-code: 0, primary-capability: document-writing}
|
||||
artifact-set-validation: {exit-code: 0, output: VALID}
|
||||
repository-layout-tests: {tests: 18, result: PASS}
|
||||
full-unittest-suite: {tests: 300, result: PASS, duration-seconds: 615.249}
|
||||
assertion-type: executed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: packages/content-job-contract/src/validate_content_job.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: packages/content-contract/src/validate_content.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: packages/workflow-runtime/src/content_runtime.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: packages/artifact-contract/src/validate_artifact_set.py
|
||||
source-kind: executed-entrypoint
|
||||
- path: tests/conformance/test_repository_layout.py
|
||||
source-kind: executed-test-module
|
||||
- path: tests
|
||||
source-kind: executed-test-suite
|
||||
|
||||
- id: F-E2E-INPUTS
|
||||
category: prerequisites
|
||||
key: end-to-end-external-inputs
|
||||
value:
|
||||
dependency-directions: [external Java/Gradle evidence repository, completed technical review file, completed narrative review file]
|
||||
part1-redraw: [external source document, completed expert review file]
|
||||
all-harness-quality: [external Java/Gradle evidence repository, stage-specific review files]
|
||||
assertion-type: declared
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: tests/end-to-end/README.md
|
||||
line-start: 68
|
||||
line-end: 139
|
||||
source-kind: end-to-end-documentation
|
||||
|
||||
- id: F-HYBRID-PENDING
|
||||
category: limitation
|
||||
key: d2-svg-layer-compositor-status
|
||||
value:
|
||||
automated-evidence: PASS
|
||||
human-qualification: PENDING
|
||||
production-status: qualification candidate, not qualified renderer
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: packages/workflow-runtime/policies/qualification.yaml
|
||||
line-start: 29
|
||||
line-end: 33
|
||||
source-kind: qualification-policy
|
||||
- path: benchmarks/hybrid-composition/results/d2-svg-layer-compositor-qualification.yaml
|
||||
line-start: 1
|
||||
line-end: 9
|
||||
source-kind: automated-qualification-result
|
||||
- path: benchmarks/hybrid-composition/results/d2-svg-layer-compositor-qualification.yaml
|
||||
line-start: 65
|
||||
line-end: 72
|
||||
source-kind: human-qualification-result
|
||||
|
||||
- id: F-BENCHMARK-MATURITY
|
||||
category: limitation
|
||||
key: qualification-corpus-status
|
||||
value:
|
||||
document-writing: corpus-defined-results-pending
|
||||
image-generation: corpus-defined-results-pending
|
||||
technical-visualization: dependency-directions comparison has unexecuted conditions and pending human preference
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: benchmarks/document-writing/suite.yaml
|
||||
line-start: 1
|
||||
line-end: 32
|
||||
source-kind: benchmark-suite
|
||||
- path: benchmarks/image-quality/suite.yaml
|
||||
line-start: 1
|
||||
line-end: 41
|
||||
source-kind: benchmark-suite
|
||||
- path: benchmarks/technical-visualization/results/dependency-directions-qualification.yaml
|
||||
line-start: 1
|
||||
line-end: 25
|
||||
source-kind: benchmark-result
|
||||
|
||||
- id: F-NO-GIT-METADATA
|
||||
category: limitation
|
||||
key: repository-snapshot
|
||||
value: the supplied directory has an empty .git directory, so no commit SHA or clean/dirty Git state can be established; the README run uses a repository content hash instead
|
||||
assertion-type: observed
|
||||
confidence: high
|
||||
evidence:
|
||||
- path: .
|
||||
source-kind: filesystem-and-git-probe
|
||||
|
||||
commands:
|
||||
- id: CMD-001
|
||||
command: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
|
||||
cwd: .
|
||||
source: {path: packages/content-job-contract/README.md, line-start: 21, line-end: 25}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-19; exit code 0; recorded in this README run's execution-evidence.yaml
|
||||
level: isolated-execution
|
||||
limitations: [validates the checked-in ContentJobRequest only]
|
||||
|
||||
- id: CMD-002
|
||||
command: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 93, line-end: 96}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-19; exit code 0 and a document-writing plan was emitted; recorded in execution-evidence.yaml
|
||||
level: isolated-execution
|
||||
limitations: [plans the checked-in request but does not execute production providers]
|
||||
|
||||
- id: CMD-003
|
||||
command: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 99, line-end: 102}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-19; exit code 0 and output VALID; recorded in execution-evidence.yaml
|
||||
level: isolated-execution
|
||||
limitations: [validates the checked-in Content Manifest only]
|
||||
|
||||
- id: CMD-004
|
||||
command: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 114, line-end: 116}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-19; exit code 0 and output VALID; recorded in execution-evidence.yaml
|
||||
level: isolated-execution
|
||||
limitations: [validates the checked-in contract fixture rather than a fresh renderer run]
|
||||
|
||||
- id: CMD-005
|
||||
command: python3 -m unittest tests.conformance.test_repository_layout
|
||||
cwd: .
|
||||
source: {path: tests/conformance/test_repository_layout.py}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-19; 18 tests passed; recorded in execution-evidence.yaml
|
||||
level: isolated-execution
|
||||
limitations: [covers repository layout only, not the full suite]
|
||||
|
||||
- id: CMD-006
|
||||
command: python3 -m unittest discover -s tests -p 'test_*.py'
|
||||
cwd: .
|
||||
source: {path: README.md, line-start: 145, line-end: 149}
|
||||
verification:
|
||||
status: executed
|
||||
method: executed from the repository root on 2026-07-19; 300 tests passed in 615.249 seconds; recorded in execution-evidence.yaml
|
||||
level: full-suite-execution
|
||||
limitations: [external provider inputs required by renderer-backed end-to-end workflows were not supplied separately]
|
||||
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"git-sha": null,
|
||||
"dirty": true,
|
||||
"diff-hash": "sha256:0f6969583accd44093b1df782f287d582dfc24bbebbc56d2adefb1c2381f2854",
|
||||
"scanned-at": null,
|
||||
"file-count": 356
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
schema-version: 1
|
||||
verdict: PASS
|
||||
score: 94
|
||||
scores:
|
||||
project-specificity:
|
||||
score: 5
|
||||
evidence:
|
||||
- 개요는 세 하네스와 workflow-runtime의 책임을 바로 밝히며, 기능별 책임·계약 사슬·검토 경계를 저장소 고유 식별자와 함께 설명한다.
|
||||
- 검토를 마친 결과 예시 섹션은 F-README-SHOWCASE에 근거한 세 산출물과 출처 기록을 제시한다.
|
||||
reader-journey:
|
||||
score: 5
|
||||
evidence:
|
||||
- 결과 예시 → 먼저 실행해 보기 → 기능별 책임과 실행 과정 → 변경 위치 → 검증 → 현재 한계 순서로 독자의 핵심 과업을 따른다.
|
||||
- 첫 문단과 대상 독자 목록만 읽어도 무엇을 만드는 저장소이며 누구를 위한 것인지 파악할 수 있다.
|
||||
technical-explanation:
|
||||
score: 5
|
||||
evidence:
|
||||
- 기능별 책임 섹션은 document-writing, technical-visualization, image-generation, workflow-runtime, integrations가 맡는 일과 경계를 구분한다.
|
||||
- 요청이 결과가 되는 과정은 계약 사슬, 분기 조건, 합류 관계, 게시 승인 경계를 Mermaid 흐름도와 본문으로 설명한다.
|
||||
- 저장소 구성과 변경 위치 표는 디렉터리 나열에 그치지 않고 책임, 변경 목적, 정본 의존 방향을 연결한다.
|
||||
task-usability:
|
||||
score: 4
|
||||
evidence:
|
||||
- 먼저 실행해 보기 섹션은 준비 사항, 복사 가능한 두 명령, 실행 위치, 종료 코드와 예상 결과, 검증 범위를 함께 제시한다.
|
||||
- 검증 섹션은 계약 검사, 산출물 묶음 검사, 구성 검사, 전체 테스트를 분리해 명령별 검증 수준을 알 수 있게 한다.
|
||||
- 패키지 설정과 버전 고정값이 없어 정본 설치 명령을 제공할 수 없는 저장소 제약 때문에 완전한 신규 환경 재현에는 추가 준비가 필요하다.
|
||||
prose-clarity:
|
||||
score: 4
|
||||
evidence:
|
||||
- 문장은 대체로 독자의 행동과 확인 결과를 먼저 제시하며, 홍보성 수식어·반복 종결·번역투·영문 일반 개념 나열이 독해를 방해하지 않는다.
|
||||
- prose-report.json은 오류 0건, 경고 0건으로 PASS이며, 필요한 파일·모듈·계약·상태 식별자는 대부분 코드 형태로 구분된다.
|
||||
- 일부 README 자체를 언급하는 문장이 남아 있으나 설치 근거와 산출물 보존 위치를 설명하는 짧은 맥락이며 독자 과업을 방해하지 않는다.
|
||||
visual-judgment:
|
||||
score: 5
|
||||
evidence:
|
||||
- 검토된 이미지, 기술 시각화, 통합 문서 미리보기는 실제 산출물을 먼저 판단하려는 독자 질문에 직접 답하며 출처·해시·검토 상태 기록으로 연결된다.
|
||||
- 요청 분기와 결과 합류는 Mermaid 흐름도로 표현하고, 명령·경로·한계처럼 그림이 불필요한 부분은 텍스트와 표로 유지했다.
|
||||
hard-gates:
|
||||
passed: true
|
||||
failures: []
|
||||
reader-simulations:
|
||||
30-seconds:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 제목 아래 첫 문단과 대상 독자 목록에서 자연어 요청을 세 종류의 결과로 만드는 저장소라는 점, 작업 실행기의 역할, 대상 개발자를 확인할 수 있다.
|
||||
5-minutes:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 대표 결과 세 종류, 최소 실행 명령, 기능 책임과 계약 흐름, 저장소 구조, 검증 범위, 현재 한계를 순서대로 찾을 수 있다.
|
||||
- 명령마다 성공 신호와 검증 범위가 붙어 있어 계획 생성과 실제 외부 도구 실행을 혼동하지 않는다.
|
||||
contributor:
|
||||
outcome: PASS
|
||||
evidence:
|
||||
- 저장소 구성과 변경 위치 표에서 변경 목적별 시작 디렉터리를 찾고, 검증 섹션에서 부분 검사와 전체 테스트 명령을 확인할 수 있다.
|
||||
- 더 읽을 문서 섹션에서 ARCHITECTURE.md, 기능별 README, 실행 작업공간 정책, 예제와 평가 자료로 이동할 수 있다.
|
||||
findings: []
|
||||
@@ -0,0 +1,8 @@
|
||||
# README 품질 검토
|
||||
|
||||
- 판정: PASS
|
||||
- 점수: 94/100
|
||||
- 중대 지적: 없음
|
||||
- 한국어 문체 검사: 오류 0건, 경고 0건
|
||||
|
||||
대표 산출물을 먼저 보여 준 뒤 실행, 책임, 작업 흐름, 변경 위치, 검증, 한계로 이어지는 순서가 세 독자 모의 검토를 모두 통과했다. 패키지 설정 파일이 없어 신규 환경 설치를 하나의 명령으로 재현할 수 없는 점은 README에 한계로 명시돼 있다.
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"run-id": "20260719-reader-first-korean",
|
||||
"repo-id": "image-haness",
|
||||
"mode": "bootstrap",
|
||||
"target-repository": "/home/donghyeon/workspace/ai-tool/image-haness",
|
||||
"harness-version": "0.1.0",
|
||||
"started-at": null,
|
||||
"tool-adapter": "codex",
|
||||
"input-hashes": {}
|
||||
}
|
||||
@@ -0,0 +1,320 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"mode": "bootstrap",
|
||||
"current": "APPLIED",
|
||||
"history": [
|
||||
{
|
||||
"state": "INITIALIZED"
|
||||
},
|
||||
{
|
||||
"state": "INPUT_CAPTURED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "request",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "REPOSITORY_SNAPSHOTTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "snapshot",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"diff-hash": "sha256:0f6969583accd44093b1df782f287d582dfc24bbebbc56d2adefb1c2381f2854"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "FACTS_EXTRACTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "facts",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"fact_ids": [
|
||||
"F-IDENTITY",
|
||||
"F-REPOSITORY-LAYERS",
|
||||
"F-SIBLING-HARNESSES",
|
||||
"F-CAPABILITY-DOCUMENT",
|
||||
"F-CAPABILITY-TECHNICAL",
|
||||
"F-CAPABILITY-IMAGE",
|
||||
"F-ROUTING",
|
||||
"F-CONTRACT-CHAIN",
|
||||
"F-INTEGRATIONS",
|
||||
"F-EXAMPLE-CHAIN",
|
||||
"F-VERSIONED-VISUALS",
|
||||
"F-RUN-WORKSPACE",
|
||||
"F-PORTABLE-OUTPUT",
|
||||
"F-LOCAL-CROSS-HARNESS-OUTPUT",
|
||||
"F-LOCAL-DOCUMENT-VISUALIZATION",
|
||||
"F-LOCAL-IMAGE-OUTPUT",
|
||||
"F-README-SHOWCASE",
|
||||
"F-RUNS-NONCANONICAL",
|
||||
"F-PREREQUISITES",
|
||||
"F-NO-PACKAGE-MANIFEST",
|
||||
"F-TEST-INVENTORY",
|
||||
"F-EXECUTED-QUICK-CHECKS",
|
||||
"F-E2E-INPUTS",
|
||||
"F-HYBRID-PENDING",
|
||||
"F-BENCHMARK-MATURITY",
|
||||
"F-NO-GIT-METADATA"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "PROJECT_PROFILED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "profile",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"profile": "generic"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "brief",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
},
|
||||
{
|
||||
"name": "outline",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"section_ids": [
|
||||
"overview",
|
||||
"showcase",
|
||||
"quick-start",
|
||||
"capabilities",
|
||||
"execution-model",
|
||||
"architecture",
|
||||
"verification",
|
||||
"limitations",
|
||||
"documentation"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "README_DRAFTED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "conformance",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"sections": [
|
||||
"overview",
|
||||
"showcase",
|
||||
"quick-start",
|
||||
"capabilities",
|
||||
"execution-model",
|
||||
"architecture",
|
||||
"verification",
|
||||
"limitations",
|
||||
"documentation"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "claim_map",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"claims": [
|
||||
"C-IDENTITY",
|
||||
"C-SHOWCASE-STATUS",
|
||||
"C-SHOWCASE-PROVENANCE",
|
||||
"C-PREREQUISITES",
|
||||
"C-INSTALLATION-LIMIT",
|
||||
"C-CMD-CONTENT-JOB",
|
||||
"C-RESULT-CONTENT-JOB",
|
||||
"C-CMD-FRONT-DOOR",
|
||||
"C-RESULT-FRONT-DOOR",
|
||||
"C-DOCUMENT-CAPABILITY",
|
||||
"C-TECHNICAL-CAPABILITY",
|
||||
"C-IMAGE-CAPABILITY",
|
||||
"C-RUNTIME-CAPABILITY",
|
||||
"C-INTEGRATIONS",
|
||||
"C-CONTRACT-CHAIN",
|
||||
"C-ROUTING",
|
||||
"C-ACCEPTANCE-BOUNDARY",
|
||||
"C-FLOW-RELATIONSHIPS",
|
||||
"C-DEPENDENCY-DIRECTION",
|
||||
"C-VERIFICATION-DATE",
|
||||
"C-CMD-CONTENT-MANIFEST",
|
||||
"C-RESULT-CONTENT-MANIFEST",
|
||||
"C-CMD-ARTIFACT-SET",
|
||||
"C-RESULT-ARTIFACT-SET",
|
||||
"C-CMD-LAYOUT-TEST",
|
||||
"C-RESULT-LAYOUT-TEST",
|
||||
"C-CMD-FULL-SUITE",
|
||||
"C-RESULT-FULL-SUITE",
|
||||
"C-E2E-PREREQUISITES",
|
||||
"C-LIMIT-PACKAGING",
|
||||
"C-LIMIT-RUNS",
|
||||
"C-LIMIT-E2E",
|
||||
"C-LIMIT-BENCHMARKS",
|
||||
"C-LIMIT-HYBRID"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "VISUALS_PLANNED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "visual_plan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"visuals": [
|
||||
"content-flow",
|
||||
"showcase-dependency",
|
||||
"showcase-editorial",
|
||||
"showcase-publication"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "STRUCTURALLY_VALIDATED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "github_markdown",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
},
|
||||
{
|
||||
"name": "reader_prose",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"schema-version": 1,
|
||||
"policy-id": "korean-reader-prose-v1",
|
||||
"language": "ko-KR",
|
||||
"applicable": true,
|
||||
"scope": "candidate",
|
||||
"state": "PASS",
|
||||
"summary": {
|
||||
"errors": 0,
|
||||
"warnings": 0,
|
||||
"sentences": 78,
|
||||
"prose-characters": 2023,
|
||||
"hangul-characters": 1775
|
||||
},
|
||||
"findings": []
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "TECHNICALLY_VERIFIED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "verify",
|
||||
"ok": true,
|
||||
"warnings": [
|
||||
"manual verification required: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest tests.conformance.test_repository_layout (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest discover -s tests -p 'test_*.py' (unsupported-static-verifier)"
|
||||
],
|
||||
"data": {
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 6,
|
||||
"verified": 0,
|
||||
"manual-required": 6,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 17,
|
||||
"verified": 17,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest tests.conformance.test_repository_layout (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest discover -s tests -p 'test_*.py' (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
},
|
||||
{
|
||||
"name": "secret_scan",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": null
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "QUALITY_REVIEWED",
|
||||
"gates": [
|
||||
{
|
||||
"name": "review",
|
||||
"ok": true,
|
||||
"warnings": [],
|
||||
"data": {
|
||||
"verdict": "PASS",
|
||||
"score": 94,
|
||||
"findings": []
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"state": "READY_FOR_APPLY",
|
||||
"gates": []
|
||||
},
|
||||
{
|
||||
"state": "APPLIED",
|
||||
"gates": []
|
||||
}
|
||||
],
|
||||
"rework": {
|
||||
"iterations": 0,
|
||||
"findings": {}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
{
|
||||
"schema-version": 1,
|
||||
"state": "PASS_WITH_MANUAL",
|
||||
"verification-level": "static",
|
||||
"execution-verified": false,
|
||||
"checks": {
|
||||
"commands": {
|
||||
"total": 6,
|
||||
"verified": 0,
|
||||
"manual-required": 6,
|
||||
"failed": 0
|
||||
},
|
||||
"paths": {
|
||||
"total": 17,
|
||||
"verified": 17,
|
||||
"failed": 0
|
||||
},
|
||||
"anchors": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"readme-contracts": {
|
||||
"total": 0,
|
||||
"verified": 0,
|
||||
"failed": 0
|
||||
}
|
||||
},
|
||||
"failures": [],
|
||||
"limitations": [
|
||||
"manual verification required: python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root . (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest tests.conformance.test_repository_layout (unsupported-static-verifier)",
|
||||
"manual verification required: python3 -m unittest discover -s tests -p 'test_*.py' (unsupported-static-verifier)"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,97 @@
|
||||
schema-version: 1
|
||||
visuals:
|
||||
- id: showcase-editorial
|
||||
section: showcase
|
||||
type: artifact-showcase
|
||||
purpose: 이미지 생성 기능이 만드는 에디토리얼 결과의 구도와 질감을 보여 준다.
|
||||
placeholder-text: 검토를 통과한 이미지 생성 결과
|
||||
must-show:
|
||||
- 햇빛이 드는 작업대와 건축 모형을 조정하는 개발자
|
||||
relationships: []
|
||||
emphasize:
|
||||
- 후보 비교와 독립 검토를 거쳐 선택한 결과
|
||||
avoid:
|
||||
- 실행 기록 경로의 파일 직접 연결
|
||||
- 장식용 영웅 이미지로 오해할 설명
|
||||
require-provenance: true
|
||||
asset:
|
||||
path: docs/assets/readme-showcase/editorial-workbench.png
|
||||
provenance: docs/assets/readme-showcase/provenance.yaml
|
||||
source-run: p6-all-harness-quality-executable-clean-architecture-20260717
|
||||
sha256: sha256:aaf6a848e5a1094c6620fa2545df6e9e156b2af136d7bf7486840be93fcb10f1
|
||||
caption: 후보 세 개와 독립 검토를 거쳐 고른 에디토리얼 이미지
|
||||
placement:
|
||||
after-section-id: showcase
|
||||
accessibility:
|
||||
alt-text: 햇빛이 드는 작업대에서 개발자가 건축 모형을 손으로 조정하는 장면
|
||||
|
||||
- id: showcase-dependency
|
||||
section: showcase
|
||||
type: artifact-showcase
|
||||
purpose: 기술 시각화 기능이 호출과 소스·모듈 의존을 구분하는 방식을 보여 준다.
|
||||
placeholder-text: 검토를 통과한 기술 시각화 결과
|
||||
must-show:
|
||||
- 유스케이스 호출, 소스 코드 의존, 모듈 의존을 분리한 방향
|
||||
relationships: []
|
||||
emphasize:
|
||||
- 근거에 묶인 의미 모형에서 만든 SVG
|
||||
avoid:
|
||||
- 관계를 확인할 수 없을 정도로 작은 표시
|
||||
- 실행 기록 경로의 파일 직접 연결
|
||||
require-provenance: true
|
||||
asset:
|
||||
path: docs/assets/readme-showcase/dependency-directions.svg
|
||||
provenance: docs/assets/readme-showcase/provenance.yaml
|
||||
source-run: p6-all-harness-quality-executable-clean-architecture-20260717
|
||||
sha256: sha256:5dacb86fb637bf0ac3ae6bf6cd9f97ea1fbc7112c02edc859ef1574cc55226cf
|
||||
caption: 호출 관계와 소스·모듈 의존을 구분한 SVG
|
||||
placement:
|
||||
after-section-id: showcase
|
||||
accessibility:
|
||||
alt-text: 유스케이스 호출, 소스 코드 의존, 모듈 의존을 구분한 클린 아키텍처 방향 그림
|
||||
|
||||
- id: showcase-publication
|
||||
section: showcase
|
||||
type: artifact-showcase
|
||||
purpose: 문서 작성과 두 시각 산출물이 최종 문서에서 어떻게 합쳐지는지 보여 준다.
|
||||
placeholder-text: 검토를 통과한 통합 문서 미리보기
|
||||
must-show:
|
||||
- 한국어 본문, 에디토리얼 이미지, 의존 방향 그림이 배치된 전체 문서
|
||||
relationships: []
|
||||
emphasize:
|
||||
- 세 하네스 결과가 한 게시 문서에 함께 들어간 모습
|
||||
avoid:
|
||||
- 본문 내용을 읽을 수 있다고 과장하는 설명
|
||||
- 실행 기록 경로의 파일 직접 연결
|
||||
require-provenance: true
|
||||
asset:
|
||||
path: docs/assets/readme-showcase/publication-preview.png
|
||||
provenance: docs/assets/readme-showcase/provenance.yaml
|
||||
source-run: p6-all-harness-quality-executable-clean-architecture-20260717
|
||||
sha256: sha256:a12aaf738c3e4c4773666d96ba46f8e341065407e975c34a69a50d390102d979
|
||||
caption: 문서 작성, 이미지 생성, 기술 시각화 결과를 한 문서에 배치한 미리보기
|
||||
placement:
|
||||
after-section-id: showcase
|
||||
accessibility:
|
||||
alt-text: 에디토리얼 이미지와 의존 방향 그림을 포함한 한국어 기술 문서 전체 미리보기
|
||||
|
||||
- id: content-flow
|
||||
section: execution-model
|
||||
type: request-flow
|
||||
purpose: 작업 실행기가 요청을 세 하네스로 나누고 검토된 게시 자료로 합치는 과정을 보여 준다.
|
||||
placeholder-text: 요청 분기와 게시 자료 합류 흐름
|
||||
must-show:
|
||||
- workflow-runtime에서 세 하네스로 나뉘는 요청
|
||||
- 검토된 게시 자료에서 출력 형식으로 이어지는 결과
|
||||
relationships:
|
||||
- workflow-runtime이 하네스를 호출하고 하네스 결과를 게시 자료로 합친다.
|
||||
emphasize:
|
||||
- 하네스끼리 직접 호출하지 않는 경계
|
||||
- 검토 뒤에만 게시 자료로 합류하는 순서
|
||||
avoid:
|
||||
- 실제로 존재하지 않는 하네스 간 직접 호출
|
||||
- 렌더러나 외부 제공자 세부 정보
|
||||
placement:
|
||||
after-section-id: execution-model
|
||||
accessibility:
|
||||
alt-text: 자연어 요청이 작업 실행기에서 문서 작성, 기술 시각화, 이미지 생성으로 나뉜 뒤 검토된 게시 자료로 합쳐지는 흐름
|
||||
Reference in New Issue
Block a user