주제 기반 단계형 HTML 변환 위임 지침서

Purpose

Markdown 보고서 컬렉션을 정적 HTML site로 변환할 때 topic HTML, root/integrated page, QA/link-check를 dependency 순서대로 분리하는 절차입니다.

운영 원칙

• 권장 site depth는 root navigation, topic index pages, report pages의 3단계이며 integrated page와 guide page를 별도 섹션으로 둔다.
• 원본 Markdown 전체 archive HTML은 명시 요청이 있을 때만 만들고 기본값은 원본 MD 보존과 큐레이션 HTML site다.
• Stage 2 topic workers는 자기 html/topics/<topic>/ subtree만 작성한다.
• Stage 3 final/root worker는 모든 topic HTML이 존재한 뒤 html/index.html, html/tree.html, html/integrated/*.html을 작성한다.

절차

1. Parent Simdeong이 source tree, 사용자 요청 단위, output boundary를 확인한다.
2. 파일 수가 아니라 최상위 주제 그룹을 기준으로 worker 수를 설계한다.
3. 각 handoff에 paths, sourceManifest, scope, qualityRequirements, coveragePolicy를 명시한다.
4. 독립 topic 작업은 병렬 실행하되 final/root 작업은 모든 dependency가 존재한 뒤 별도 stage로 실행한다.
5. 소스를 직접 읽을 수 없으면 전체를 읽은 것처럼 쓰지 않고 limitation 또는 blocker를 명시한다.

Failure modes

• Final worker를 topic worker와 같은 독립 batch에 넣어 누락된 근거로 최종 보고서를 만드는 경우.
• 주제별 요청을 파일별 worker 수로 오해해 중복 산출물을 만드는 경우.
• 원본 Markdown이나 이전 산출물을 덮어써 근거 추적성을 잃는 경우.
• 명시 요청 없이 archive/original HTML을 생성하는 경우.
• Cloudflare URL처럼 completion workflow가 반환해야 할 값을 writer가 임의로 주장하는 경우.

Stage 3 static HTML. Relative links only.