Files

T

DongHyeonka c708cbcf9a init: readme 작성 하네스 설계

2026-07-24 13:26:18 +09:00

16 KiB

Raw Blame History

Content Harness

Content Harness는 자연어 기반 콘텐츠 요청을 문서 계획, 정확한 기술 시각화, 유기적 이미지 생성, 검토된 publication output으로 연결하는 provider-neutral Python 시스템입니다.

문서 작성과 기술 도형, 유기적 이미지에는 서로 다른 생성·검토 기준이 필요합니다. 이 저장소는 세 production harness를 sibling으로 유지하고, workflow-runtime만 라우팅·DAG 실행·결과 전달·publication을 조정하도록 책임을 나눕니다.

이 README는 저장소를 처음 평가하는 개발자에게는 실행 가능한 contract chain을, 기여자에게는 capability별 변경 위치를, 리뷰어에게는 실제 생성 산출물과 현재 qualification 한계를 보여줍니다.

책임이 섞이지 않는 네 capability

Document Writing

document-writing은 독자·서사·근거 연결·시각화 기회를 다루고, ContentJobRequest·Content Manifest·Narrative Plan·publication draft·Visual Request를 만듭니다. 원문을 제자리에서 덮어쓰거나 renderer와 image provider를 선택하지 않습니다.

Technical Visualization

technical-visualization은 근거에 묶인 semantic model, visual grammar, D2 렌더링, 문서·발표용 rendition을 소유합니다. 현재 실행 가능한 visual type은 dependency-graph와 runtime-sequence이며, accepted ArtifactSet에는 서로 다른 reviewer가 작성한 technical-semantic·technical-visual review가 필요합니다.

Image Generation

image-generation은 사진·일러스트·재질·분위기 같은 organic raster를 소유합니다. production 경로는 해시된 후보 3개, pairwise comparison, 명시적 선택, 최대 한 번의 bounded repair를 사용하며, exact architecture relation·chart·state machine·긴 정확 텍스트는 이 capability의 범위 밖입니다.

Workflow Runtime과 Integrations

workflow-runtime은 contract validation, routing, cycle-free DAG, freshness, retry, immutable result 수집, integration dispatch, event와 portable output publication을 소유합니다. sibling harness는 서로를 직접 호출하지 않습니다.

Markdown·Slides·HTML adapter는 runtime이 선택해 동결한 publication projection 하나만 소비하며, 내용·관점·route·renderer·provider를 다시 결정하지 않습니다.

2분 검증

전제 조건

핵심 contract와 runtime은 Python 3에서 동작하며 PyYAML과 jsonschema를 사용합니다. Raster 검증·preview에는 Pillow가, technical rendering에는 D2가, SVG의 browser preview에는 Chrome 또는 Chromium이 필요합니다. 저장소는 이 도구들의 버전을 고정하지 않습니다.

현재 저장소에는 pyproject.toml, requirements.txt, setup.py, setup.cfg, Pipfile, poetry.lock, uv.lock이 없어 하나의 정본 설치 명령을 제시할 수 없습니다. 필요한 도구를 환경에 준비한 뒤 아래 검증을 실행하십시오.

1. 자연어 요청의 contract 확인

python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .

이 명령은 이번 README 작성 세션에서 exit code 0으로 완료됐습니다. 출력 없이 종료되면 체크인된 ContentJobRequest가 현재 contract를 통과한 것입니다.

2. Front door 계획 확인

python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .

이 명령도 exit code 0으로 완료됐고 primary_capability: document-writing인 plan을 출력했습니다. 이는 계획 단계의 확인이며 author·review provider를 호출하는 production 실행은 아닙니다.

요청에서 publication까지

Contract chain은 ContentJobRequest → Content Manifest → Narrative Plan → Visual Request → ArtifactSet → frozen publication projection 순서로 책임을 좁혀 갑니다. JSON Schema는 구조를, Python validator는 현재 파일 hash·safe path·cross-contract ID·evidence·routing·freshness처럼 schema만으로 표현하기 어려운 조건을 확인합니다.

Visual Request의 신호가 technical-only이면 technical-visualization, image-only이면 image-generation, 둘 다이면 runtime-owned hybrid DAG로 라우팅됩니다. 신호가 없으면 BLOCKED_UNRESOLVED, 명시적 충돌이면 ROUTING_CONFLICT입니다.

각 harness는 plan 또는 immutable JobResult를 runtime에 반환합니다. Runtime만 sibling 결과를 조립하고 accepted rendition의 publication projection을 동결해 integration adapter로 넘깁니다.

Deterministic validation은 expert review를 대신하지 않습니다. 필수 review가 없는 유효한 technical 결과는 produced에 머물며 accepted나 integration-ready로 승격되지 않습니다.

다음 흐름은 request와 contract가 runtime에서 sibling capability로 분기한 뒤 reviewed draft 또는 accepted ArtifactSet으로 합류하는 지점을 요약합니다.

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"]

생성 산출물 둘러보기

버전 관리되는 contract example

Clean Architecture 예제는 ContentJobRequest부터 Visual Request와 ArtifactSet까지 이어지는 체크인된 contract chain입니다. artifact/attempt-01/에는 document·presentation·reveal-step SVG와 accepted/ready 상태의 manifest가 있지만, 이는 renderer-backed golden이 아니라 최소 contract fixture입니다.

현재 작업 사본의 로컬 테스트 산출물

현재 작업 사본에는 문서 작성·기술 시각화·이미지 생성을 함께 통과시킨 로컬 P6 결과가 있습니다. runs/p6-all-harness-quality-executable-clean-architecture-20260717/output/ 아래에는 final-document.md, index.html, 전체 문서 preview.png, 문서·발표용 dependency-direction SVG, organic PNG 두 target, image candidate contact sheet와 validation manifest가 있습니다.

문서와 기술 시각화를 함께 시험한 runs/docvis-20260716-executable-clean-architecture-part1/에는 통합 HTML, desktop·mobile 문서 preview, 두 figure의 target별 SVG와 PNG fallback, delivery·asset manifest가 있습니다.

Best-of-three 이미지 예제인 runs/img-20260716-japanese-animation-test/는 3개 후보 중 attempt 2를 BEST_OF_N_PASS로 선택하고 outputs/final-selected.png를 남겼습니다.

산출물 유형	로컬 예시	확인할 것
생성 문서	`output/final-document.md`, `output/index.html`, `output/preview.png`	Markdown·HTML·전체 페이지 preview와 delivery manifest
기술 시각화	`assets/dependency-directions.document.svg`, `assets/dependency-directions.presentation.svg`	같은 semantic source의 target별 크기·표현
생성 이미지	`assets/editorial-workbench.document.png`, `assets/editorial-workbench.presentation.png`	target별 organic rendition과 선택된 candidate hash
비교·검토 자료	`assets/image-candidates.png`, `validation-summary.yaml`	후보 contact sheet와 capability별 validation 결과

runs/**는 .gitignore 대상인 로컬 immutable 실행 작업공간이며 cache나 source of truth가 아닙니다. 새 실행은 runs/<purpose>/run-<YYYYMMDDTHHMMSSZ>-NNN/을 할당하고, reviewed deliverable이 있으면 <run-root>/output/index.html과 hash-bound manifest.yaml을 만들 수 있습니다.

따라서 위 로컬 PNG·SVG를 README에 직접 임베드하지 않았습니다. GitHub에서 지속되는 gallery가 필요하면 검토된 파일을 examples/ 또는 별도 versioned 문서 asset 경로로 승격하고, provenance와 manifest를 함께 갱신해야 합니다.

자세한 실행 데이터 정책은 Runtime workspace를 참고하십시오.

저장소 구조와 변경 위치

경로	정본 책임	변경할 때 함께 볼 곳
`.agents/`, `.codex/`	AI 도구의 thin discovery adapter	해당 capability의 `harnesses/` 정본
`harnesses/`	document·technical visual·image capability 정책과 구현	`packages/` contract, capability test
`packages/`	contract, schema support, workflow runtime	schema fixture, conformance·runtime test
`integrations/`	frozen projection을 받는 Markdown·Slides·HTML adapter	publication adapter test
`tests/`	conformance, contract, runtime, failure injection, E2E	`tests/golden/` regression oracle
`examples/`	versioned executable contract chain	validator와 example manifest
`benchmarks/`	suite, failure corpus, qualification result	policy의 qualification 상태
`runs/`	ignored local execution data	`runs/README.md`; 정본으로 사용 금지

이 소유권 지도에서 .agents/.codex는 adapter, harnesses는 capability 구현, packages는 contract와 runtime, integrations는 publication target을 담당합니다.

정본 의존 방향은 adapter → harnesses → packages이며, workflow-runtime은 handler registry를 통해 harness를 실행하고 frozen projection만 integrations로 보냅니다. Contract와 integration adapter가 harness implementation을 역으로 소유하지 않습니다.

구체적인 contract chain과 hybrid composition 경계는 ARCHITECTURE.md에 있습니다.

검증 명령과 증거 수준

이번 README 작업에서는 다음 세 검증도 저장소 루트에서 실제 실행했습니다.

python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .

결과: VALID, exit code 0.

python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml

결과: VALID, exit code 0. 이 검증은 체크인된 contract fixture를 대상으로 하며 fresh renderer execution을 대신하지 않습니다.

python3 -m unittest tests.conformance.test_repository_layout

결과: 18개 test가 통과했습니다. 이 범위는 canonical directory와 adapter boundary를 확인하며 전체 suite를 대신하지 않습니다.

전체 discovery 명령은 다음과 같이 정의돼 있습니다.

python3 -m unittest discover -s tests -p 'test_*.py'

전체 suite는 이번 README 작업에서 재실행하지 않았습니다. 2026-07-18 refactoring review는 별도의 300-test pass를 기록하지만, 이를 이번 실행 결과로 재표현하지 않습니다.

Renderer-backed E2E는 외부 Java/Gradle evidence repository, 외부 source document 또는 scope별 expert review 파일을 요구합니다. exact run root를 단계 사이에 전달하는 명령은 End-to-end workflows에 분리돼 있습니다.

현재 상태와 한계

설치 재현성: dependency packaging manifest와 version pin이 없으므로 README는 임의의 패키지 설치 명령이나 최소 버전을 만들지 않습니다.
산출물 지속성: 실제 PNG·SVG·HTML·Markdown 샘플은 로컬 runs/에 있지만 clean checkout이나 GitHub 링크의 영속성을 보장하지 않습니다.
Benchmark 성숙도: document-writing과 image-generation suite는 corpus만 정의되고 결과가 pending입니다. Technical visualization의 dependency-direction 비교도 일부 condition과 human preference가 남아 있습니다.
Hybrid qualification: d2-svg-layer-compositor의 자동 16-case 증거는 PASS지만 human Gate 3는 PENDING입니다. 이 renderer는 qualification candidate이며 qualified renderer로 소개하면 안 됩니다.
E2E 입력: 전체 품질·dependency-direction·redraw 경로는 이 저장소만으로 완결되지 않고 외부 evidence/source와 완료된 expert review를 요구합니다.

문서와 정본 지도

정본 설계는 ARCHITECTURE.md, 문서 색인은 docs/README.md, 실행 작업공간 정책은 runs/README.md에 있습니다.

Architecture — layering, contract chain, routing, review authority, run identity
Documentation map — 현재 문서와 historical implementation 기록의 구분
Runtime workspace — fresh allocation, exact resume, output publication
Document Writing Harness
Technical Visualization Harness
Image Generation Harness
Workflow Runtime
Clean Architecture example
End-to-end workflows
Benchmarks · image quality · hybrid composition

과거 phase 문서는 구현 이력일 뿐 현재 capability 정의가 아닙니다. 현재 동작을 바꿀 때는 위 정본과 관련 contract·test·benchmark를 함께 갱신하십시오.

16 KiB Raw Blame History