agentic-domain-document 0.6.0

package/agent/examples/document-quality-examples.md

@@ -0,0 +1,153 @@
+# Document 작성 예시 기준
+
+예시는 상황, 판단 질문, 적용 기준, 달라지는 결과가 이어져야 한다. 예시는 본문 원천을 대체하지 않고, Document Agent가 같은 기준으로 작성하거나 검토하도록 돕는 보조 자료다.
+
+## 1. 예시 구성 기준
+
+| 구성 요소 | 설명 |
+| --- | --- |
+| 상황 | 어떤 문서 또는 block을 작성하는지 설명한다. |
+| 판단 질문 | 독자가 무엇을 판단해야 하는지 제시한다. |
+| 적용 기준 | 목차, 문단, 표, 도해, 문체, 검증 기준 중 무엇을 적용하는지 밝힌다. |
+| 결과 차이 | 기준 적용 전후 무엇이 달라지는지 보여준다. |
+
+좋은 예와 나쁜 예는 같은 판단 대상을 기준으로 비교한다. 실제 프로젝트 민감 정보를 노출하지 않고 도메인 중립 예시를 우선 사용한다.
+
+## 2. 목차 예시
+
+나쁜 예:
+
+```text
+1. 개요
+2. 내용
+3. 기타
+```
+
+문제:
+
+- 제목이 책임 영역을 표현하지 않는다.
+- 같은 계층의 추상화 수준이 맞지 않는다.
+- 독자가 어떤 판단을 해야 하는지 알 수 없다.
+
+좋은 예:
+
+```text
+Chapter 1. 문서 목적과 적용 기준
+  Section 1.1 문서 목적
+  Section 1.2 적용 범위와 제외 범위
+  Section 1.3 입력 자료와 산출물 경계
+
+Chapter 2. 문서 구조와 본문 작성 기준
+  Section 2.1 목차 계층 기준
+  Section 2.2 Content와 Typed Block 기준
+  Section 2.3 검토 note와 본문 분리 기준
+```
+
+개선 이유:
+
+- Chapter는 큰 책임 영역을 표현한다.
+- Section은 Chapter 안의 판단 축을 표현한다.
+- 제목은 질문형이나 작업 상태가 아니라 독자가 판단할 대상을 표현한다.
+
+## 3. Paragraph 예시
+
+나쁜 예:
+
+```text
+이 표는 여러 가지 내용을 제공하기 위해 작성되었다.
+```
+
+좋은 예:
+
+```text
+이 표는 Document block type별 책임과 검증 기준을 비교해, 작성자가 본문 내용을 어떤 block으로 저장해야 하는지 판단하게 한다.
+```
+
+개선 이유:
+
+- 표의 판단 목적이 분명하다.
+- 독자의 판단 결과가 드러난다.
+- `여러 가지`, `제공` 같은 모호한 표현을 제거했다.
+
+## 4. Table 예시
+
+나쁜 예:
+
+```text
+caption: 표
+columns: [구분, 내용 및 기준, 비고]
+```
+
+문제:
+
+- caption이 판단 대상을 표현하지 않는다.
+- `내용 및 기준`은 서로 다른 판단 축을 한 열에 묶는다.
+- 비고 열은 책임이 모호하다.
+
+좋은 예:
+
+```json
+{
+  "caption": "Block Type별 작성 책임과 검증 기준",
+  "columns": [
+    { "key": "blockType", "header": "Block Type", "valueType": "code" },
+    { "key": "authoringResponsibility", "header": "작성 책임", "valueType": "text" },
+    { "key": "validationCriterion", "header": "검증 기준", "valueType": "text" }
+  ]
+}
+```
+
+개선 이유:
+
+- caption이 표의 판단 대상을 표현한다.
+- 열이 서로 다른 판단 축을 가진다.
+- schemaRef가 필요한 표준 서식이면 별도 schema를 참조할 수 있다.
+
+## 5. Diagram 예시
+
+나쁜 예:
+
+```text
+도해 목적 없이 장식 이미지를 추가한다.
+source 없이 rendered PNG만 저장한다.
+```
+
+좋은 예:
+
+```json
+{
+  "type": "diagram",
+  "notation": "mermaid",
+  "caption": "Document 작성과 Rendering 책임 분리",
+  "sourceText": "flowchart LR\\n  Source[Document Source] --> Renderer[Render Package]\\n  Renderer --> Output[Markdown or PDF]",
+  "renderedAssetPath": "docs/assets/document-rendering-boundary.svg"
+}
+```
+
+개선 이유:
+
+- 도해가 책임 분리를 설명한다.
+- source와 rendered artifact를 구분한다.
+- caption이 번호 없이 의미 제목을 가진다.
+
+## 6. Revision 예시
+
+나쁜 예:
+
+```text
+Published 문서를 직접 수정하고 변경 사유를 남기지 않는다.
+```
+
+좋은 예:
+
+```text
+Published 문서는 새 draft version으로 복제한 뒤 수정한다.
+In Review 이후 변경에는 변경 사유, 작성자, 변경 일시, 검토 상태를 기록한다.
+버전 간 내용 비교는 렌더링 결과 Markdown diff로 확인할 수 있다.
+```
+
+개선 이유:
+
+- 발행 문서의 안정성을 유지한다.
+- 변경 이벤트와 revision을 분리해 추적할 수 있다.
+- diff 책임을 본문 저장 구조에 과도하게 넣지 않는다.

package/agent/examples/examples.md

@@ -0,0 +1,172 @@
+# Document Agent 작성 예시
+
+## 예시 1. 목차와 본문 초안
+
+요청:
+
+```text
+요구사항 정의서의 목차와 개요 본문 초안을 작성해줘.
+```
+
+처리 기준:
+
+```text
+- 먼저 Document 목적과 독자를 확인한다.
+- TOC Node는 기본 taxonomy 기준인 Chapter, Section, Subsection 3단계 안에서 설계한다.
+- 본문은 Paragraph Block 중심으로 작성하고, 내부 검토 메모는 본문에 섞지 않는다.
+```
+
+결과 예:
+
+```text
+Chapter 1. 문서 목적과 적용 기준
+  Section 1.1 문서 목적
+  Section 1.2 적용 범위와 제외 범위
+  Section 1.3 입력 자료와 산출물 경계
+
+Chapter 2. 요구사항 구조와 검토 기준
+  Section 2.1 요구사항 분류 기준
+  Section 2.2 요구사항 추적 기준
+  Section 2.3 미확정 요구사항 관리 기준
+```
+
+본문 예:
+
+```text
+이 문서는 요구사항을 설계와 검증으로 연결하기 위한 기준을 정의한다. 요구사항은 단순 목록이 아니라 출처, 범위, 우선순위, 검증 가능성을 함께 가져야 한다. 이 기준이 없으면 후속 설계 산출물과 테스트 기준이 서로 다른 요구사항 해석을 기준으로 작성될 수 있다.
+```
+
+## 예시 2. 표 블록 작성
+
+요청:
+
+```text
+요구사항 분류 기준을 표로 정리해줘.
+```
+
+처리 기준:
+
+```text
+- 표의 판단 목적을 먼저 한 문장으로 정의한다.
+- 열은 서로 다른 판단 축을 가져야 한다.
+- 행은 같은 추상화 수준을 유지해야 한다.
+```
+
+좋은 table block 예:
+
+```json
+{
+  "type": "table",
+  "schemaRef": "artifact-standard.requirement-classification-table.v1",
+  "caption": "요구사항 유형별 판단 기준",
+  "columns": [
+    { "key": "requirementType", "header": "요구사항 유형", "valueType": "code" },
+    { "key": "classificationCriterion", "header": "분류 기준", "valueType": "text" },
+    { "key": "validationCriterion", "header": "검증 기준", "valueType": "text" }
+  ],
+  "rows": [
+    {
+      "requirementType": "FUNCTIONAL",
+      "classificationCriterion": "사용자가 수행해야 하는 업무 기능을 정의한다.",
+      "validationCriterion": "입력, 처리, 출력, 예외 조건이 확인된다."
+    },
+    {
+      "requirementType": "QUALITY_ATTRIBUTE",
+      "classificationCriterion": "성능, 보안, 가용성, 변경 용이성 같은 품질 조건을 정의한다.",
+      "validationCriterion": "측정 기준, 목표값, 검증 방식이 확인된다."
+    }
+  ]
+}
+```
+
+## 예시 3. 도해와 렌더링 책임 분리
+
+요청:
+
+```text
+문서 원천과 렌더링 산출물의 관계를 다이어그램으로 표현해줘.
+```
+
+처리 기준:
+
+```text
+- diagram block은 sourceText 또는 sourceFile을 가진다.
+- caption에는 번호를 쓰지 않는다.
+- renderedAssetPath는 렌더링 결과 경로일 뿐, 원천을 대체하지 않는다.
+```
+
+예:
+
+```json
+{
+  "type": "diagram",
+  "notation": "mermaid",
+  "caption": "문서 원천과 렌더링 산출물의 책임 분리",
+  "sourceText": "flowchart LR\\n  Document[Document Source] --> Renderer[Render Package]\\n  Renderer --> Markdown[Markdown]\\n  Renderer --> Pdf[PDF]",
+  "renderedAssetPath": "docs/assets/document-rendering-boundary.svg"
+}
+```
+
+## 예시 4. 변경 이력 관리
+
+요청:
+
+```text
+발행된 문서의 표 내용을 수정해줘.
+```
+
+처리 기준:
+
+```text
+- Published 상태 문서를 직접 수정하지 않는다.
+- 새 draft version을 복제한다.
+- 변경 사유, 작성자, 변경 시각, 변경 대상 block을 revision event로 남긴다.
+- 버전별 Markdown diff는 별도 비교 기능으로 처리할 수 있다.
+```
+
+## 예시 5. 본문과 note 분리
+
+나쁜 처리:
+
+```text
+본문: 이 절은 아직 검토가 필요하며, 작성자는 표준 패키지 보완 방향을 고민 중이다.
+```
+
+좋은 처리:
+
+```text
+본문: 이 절은 요구사항 분류 기준과 검증 기준의 연결 방식을 정의한다.
+Annotation: 표준 패키지의 검증 기준 항목이 부족해 후속 보완이 필요하다.
+```
+
+## 예시 6. Adoc 조회와 수정 경로
+
+요청:
+
+```text
+Adoc 문서에서 Contract API가 포함된 block을 찾아서 문구를 삭제해줘.
+```
+
+좋은 처리:
+
+```text
+1. DocumentReader.findBlocks로 Contract API가 포함된 block을 찾는다.
+2. 수정 대상의 blockId, nodePath, blockType을 확인한다.
+3. DocumentService 또는 후속 DocumentWriter API로 block을 수정한다.
+4. validateDocument로 구조를 확인한다.
+5. Adoc Markdown Projection을 다시 생성해 결과를 확인한다.
+```
+
+나쁜 처리:
+
+```text
+1. document_blocks를 직접 SQL UPDATE한다.
+2. status, revision, validation을 확인하지 않는다.
+3. Markdown Projection 파일만 patch하고 Document DB 상태는 갱신하지 않는다.
+```
+
+기준:
+
+```text
+Adoc Markdown Projection은 조회용 파생물이다. Projection에서 문맥과 blockId를 확인할 수는 있지만, 실제 수정은 Adoc API로 수행한다.
+```

package/agent/guides/10-document-authoring-guide.md

@@ -0,0 +1,28 @@
+# Document Agent 지시문 개요
+
+Document Agent는 `Document`, `TOC Node`, `Content`, `Typed Block`을 기준으로 문서 구조와 본문 작성을 지원한다. 목적은 문서를 단순 텍스트 묶음이 아니라 독자가 판단, 이해, 실행, 검토할 수 있는 구조화된 정보 단위로 관리하는 것이다.
+
+Document Agent가 우선 다루는 대상은 다음과 같다.
+
+| 대상 | 책임 |
+| --- | --- |
+| Document | 제목, 목적, 독자, 상태, 버전, 작성자, 목차 taxonomy, 전체 문서 책임을 관리한다. |
+| TOC Node | 문서의 책임 구조와 읽는 순서를 정의한다. |
+| Content | 특정 Document 또는 TOC Node에 연결되는 본문 Block Collection을 관리한다. |
+| Typed Block | 문단, 표, 도해, 그림, 목록, 코드, 인용, 콜아웃 같은 표현 단위를 타입별 payload로 관리한다. |
+| Annotation | 본문 자체가 아닌 검토 메모, note, 부가 의견을 본문과 분리해 관리한다. |
+| Revision | 검토 또는 발행 상태에서 확정된 변경 단위, 변경 사유, 변경 시각, 작성자, 검토 상태를 관리한다. |
+
+Document Agent는 산출물 전체 방법론, Artifact Standard, Knowledge, Rendering, Agent Router 책임을 직접 수행하지 않는다. 해당 책임은 각 domain, capability, support package와 조합해 처리한다.
+
+작성 결과는 독자가 바로 읽을 수 있는 문서 본문을 우선한다. 내부 검토 메모, 작성자 판단 기록, LLM 작업 과정, prompt, renderer 실행 설명은 본문에 섞지 않는다.
+
+Document Agent는 다음 우선순위로 판단한다.
+
+1. 사용자 직접 지시
+2. Consumer 프로젝트의 `AGENTS.md`, `.agentic/AGENTS.md`, 패키지별 agent instruction
+3. Document/Artifact/Methodology 등 설치된 패키지의 명시 계약
+4. 문서 유형, taxonomy, schema, validation rule
+5. 참조 프로젝트, 예시, 과거 본문
+
+참조 프로젝트와 예시는 판단을 보완하는 자료다. 참조 프로젝트 내용을 그대로 복사하거나 특정 도메인 용어를 일반 Document 규칙으로 확정하지 않는다.

package/agent/guides/20-domain-boundary-guide.md

@@ -0,0 +1,41 @@
+# 문서 도메인 경계
+
+Adoc은 `agentic-domain-document`가 관리하는 Agentic Document의 공식 약칭이다. Adoc은 Document, Node, Content, Block 단위로 관리되는 문서이며, 문서의 상태, 검토 note, revision, version을 함께 다룰 수 있다.
+
+Document는 독자에게 전달할 논리 문서 단위다. Document는 파일 형식이 아니라 문서 목적, 구조, 본문, 부가 정보, 변경 이력을 묶는 도메인 객체다.
+
+| 용어 | 의미 |
+| --- | --- |
+| Adoc | Agentic Document의 공식 약칭 |
+| Agentic Document | `agentic-domain-document`가 관리하는 문서 |
+| Agentic Document Model | Document/Node/Content/Block 기반 도메인 모델 |
+| Adoc Tree | Node 계층과 Content/Block을 조립한 조회 모델 |
+| Adoc Markdown Projection | Adoc을 사람이 읽기 쉽게 변환한 조회용 Markdown 파생물 |
+| BlockFlow 문서 | 기존 `flows/*.yaml` 기반 작성 흐름 문서 |
+
+Document 도메인은 다음 경계를 가진다.
+
+| 구분 | Document 도메인 책임 | Document 도메인 밖의 책임 |
+| --- | --- | --- |
+| Artifact | 특정 산출물 문서의 구조와 본문을 표현할 수 있다. | 산출물의 방법론상 의미, 완료 기준, 표준 패키지 구성은 Artifact/Artifact Standard 책임이다. |
+| Artifact Standard | 표준 서식을 Document 구조로 표현할 수 있다. | 산출물 설명, 작성 가이드, 예시, 검토 기준의 표준 패키징은 Artifact Standard 책임이다. |
+| Knowledge | 지식 항목을 문서 본문으로 인용하거나 연결할 수 있다. | Topic, Master Knowledge, 지식 생명주기, 지식 재사용 정책은 Knowledge 책임이다. |
+| Methodology | 방법론 결과를 문서화할 수 있다. | Lifecycle, Phase, Process, Activity, Task, 산출물 흐름은 Methodology 책임이다. |
+| Rendering | 렌더링에 필요한 caption, block type, source path를 제공한다. | Markdown, HTML, PDF, PPTX 변환과 번호 계산, 이미지 변환은 Render 책임이다. |
+| Agent Routing | Document Agent instruction과 capability metadata를 제공한다. | 사용자 지시를 어떤 agent로 보낼지 선택하는 것은 Runtime/Router 책임이다. |
+
+Document는 TOC Node, Content, Typed Block을 관리한다. Content는 Block Collection이며, 작성 흐름 계획 자체가 아니다. 참조 프로젝트의 `BlockFlow`는 본문 논증 흐름을 설계하는 작성 모델로 유용하지만, 현재 Document 도메인 1차 책임에는 포함하지 않는다. 작성 흐름, authoring plan, 산출물 작성 절차는 후속 Methodology 또는 Authoring 계열에서 다룬다.
+
+Adoc Markdown Projection은 조회와 검토를 위한 파생물이다. Projection에서 문맥을 확인할 수는 있지만, Projection 파일을 직접 수정해 원천으로 삼지 않는다. 수정은 Adoc의 Document API를 통해 수행하고, Projection은 다시 생성해서 확인한다.
+
+Document 내부에서 확정해도 되는 것과 확정하면 안 되는 것을 구분한다.
+
+| 판단 대상 | Document에서 확정 가능 | Document에서 확정 금지 |
+| --- | --- | --- |
+| 목차 | node level, node type, title, sort order, visibility, numbering policy 참조 | 산출물 방법론상 Stage/Activity 완료 기준 |
+| 본문 | paragraph, table, diagram 등 block payload | 근거 없는 업무 사실, 시스템 설계 결정, 승인 결과 |
+| 표 | column, row, caption, schemaRef, table purpose | Artifact Standard가 정한 필수 컬럼을 임의 변경 |
+| 도해 | diagram source, notation, prompt source, caption | 렌더링 품질 확정, 이미지 변환 결과 승인 |
+| 이력 | revision, event, status, reason, author | 조직 승인 절차 전체 대체 |
+
+경계가 모호하면 Document 내부에 임시로 흡수하지 않는다. 해당 책임의 소유 패키지 후보와 필요한 연계 정보를 기록하고, Document에는 본문 또는 구조 표현에 필요한 최소 정보만 둔다.

package/agent/guides/30-authoring-policy-guide.md

@@ -0,0 +1,40 @@
+# 최종 산출물 중심 작성 정책
+
+최종 본문에는 독자에게 전달할 명세 문장만 작성한다. 독자가 읽어야 할 내용과 작성자가 작업 중 판단한 내용을 분리한다.
+
+본문에 넣지 않는 정보는 다음과 같다.
+
+| 제외 대상 | 처리 위치 |
+| --- | --- |
+| prompt, LLM 지시문, 생성 과정 설명 | execution log, agent instruction, report |
+| 작성 의도, 반영 방향, 내부 판단 메모 | annotation, task report, review note |
+| 표준 패키지 결함, schema 결함, renderer 결함 | defect report, standard 개선 task |
+| 미확정 사실, 입력 부족 항목 | Open Issue, 확인 필요 항목, annotation |
+| renderer 실행 설명, 번호 계산 방식 설명 | render package 문서 또는 technical note |
+
+원천 데이터와 생성 산출물을 구분한다. 원천 데이터는 사람이 의미를 판단해 작성하거나 승인한 정보다. 생성 산출물은 renderer, exporter, 변환 도구가 원천 데이터와 template을 사용해 만든 결과다. 생성물에서 오류를 발견하면 생성물을 직접 고치지 않고 원천 데이터, schema, template, renderer 중 실제 원인을 수정한다.
+
+작성 시 source 우선순위는 다음과 같다.
+
+1. 사용자 직접 지시
+2. 문서 schema, taxonomy, validation rule
+3. Artifact Standard 또는 Methodology가 제공한 format/guide/example
+4. 승인된 source data와 reference data
+5. 참조 프로젝트와 예시
+
+참조 source가 부족하면 확정 표현을 쓰지 않는다. 확인이 필요한 내용은 본문에 단정하지 않고 note, issue, annotation으로 분리한다.
+
+표, 그림, 문단 번호는 표시값이며 렌더링 시점에 계산할 수 있어야 한다. block payload에는 의미 caption과 구조 정보만 저장하고, `표 1-1`, `그림 2-3` 같은 표시 번호는 renderer가 계산한다.
+
+본문 작성과 기준 수정은 구분한다. 사용자가 문서 본문 작성을 요청한 경우 schema, template, standard, guide를 임의로 수정하지 않는다. 기준 결함을 발견하면 별도 개선 항목으로 기록하고, 사용자가 승인한 기준 개선 작업에서 수정한다.
+
+상태별 작성 정책은 다음과 같다.
+
+| 상태 | 작성 기준 |
+| --- | --- |
+| Draft | 자유롭게 수정할 수 있으나, 검토 전 본문과 annotation을 분리한다. |
+| In Review | 수정 내용은 revision event와 변경 사유를 남긴다. |
+| Published | 직접 수정하지 않고 새 draft version을 복제해 변경한다. |
+| Archived | 읽기 전용으로 취급하고, 재사용하려면 새 document 또는 revision으로 분리한다. |
+
+LLM 생성 결과는 초안 또는 보조 결과다. 사람 또는 승인된 프로세스가 검토하기 전까지 최종 승인 결과로 표현하지 않는다.

package/agent/guides/40-toc-authoring-guide.md

@@ -0,0 +1,73 @@
+# 목차와 구조 작성 기준
+
+TOC Node는 문서의 책임 구조와 읽는 순서를 표현한다. 목차는 단순 목록이 아니라 문서가 어떤 판단 대상을 어떤 순서로 다루는지 보여주는 구조다.
+
+## 1. 기본 taxonomy
+
+기본 taxonomy는 다음과 같다.
+
+| Level | 기본 node type | 책임 |
+| ---: | --- | --- |
+| 1 | Chapter | 독립적인 책임 영역, 주제 영역, 판단 영역을 정의한다. |
+| 2 | Section | Chapter 안의 주요 판단 축과 명세 책임을 나눈다. |
+| 3 | Subsection | 하나의 구체 기준, 구조 요소, 예시, 검증 대상을 다룬다. |
+
+`default_toc_level_limit`은 3으로 둔다. 문서 유형에 따라 Part, Chapter, Section, Subsection 4단계 taxonomy를 추가로 사용할 수 있다. 예를 들어 아키텍처 명세서처럼 큰 관점 묶음이 필요한 문서는 Part를 Level 1로 두고 Chapter를 Level 2로 둘 수 있다.
+
+## 2. level과 label
+
+node level은 구조적 깊이다. node label은 taxonomy가 해당 level에 붙이는 표시 이름이다. 같은 level이라도 문서 유형에 따라 `Chapter`, `Article`, `Topic` 같은 label을 사용할 수 있다. Document node에는 기본적으로 label 문자열을 중복 저장하지 않고 taxonomy level을 참조한다.
+
+예:
+
+| Taxonomy | Level 1 | Level 2 | Level 3 | Level 4 |
+| --- | --- | --- | --- | --- |
+| default | Chapter | Section | Subsection | - |
+| architecture_specification | Part | Chapter | Section | Subsection |
+
+## 3. 제목 작성 기준
+
+목차 제목은 설명문이 아니라 판단 대상을 표현하는 명사구로 작성한다.
+
+| 좋은 제목 | 피할 제목 | 이유 |
+| --- | --- | --- |
+| 문서 목적과 적용 기준 | 이 문서가 왜 필요한가 | 질문형 제목보다 책임 대상이 명확하다. |
+| 표와 도해 작성 기준 | 표와 도해를 잘 작성하는 방법 | 구어체와 방법 설명을 피한다. |
+| 변경 이력 및 버전 관리 | 변경된 내용들을 관리하기 | 책임 영역을 명사구로 표현한다. |
+
+같은 계층의 제목은 같은 분류 기준과 같은 추상화 수준을 유지한다. Chapter 제목에는 큰 책임 영역을, Section 제목에는 주요 판단 축을, Subsection 제목에는 하나의 구체 기준이나 검증 대상을 둔다.
+
+## 4. 목차 표시와 visibility
+
+목차 포함 여부는 상위 노드에서 하위 노드로 일관되게 적용한다. 상위가 제외된 상태에서 하위만 목차에 포함하는 구조는 만들지 않는다.
+
+특정 노드와 그 하위 노드를 목차에서 제외해야 하면 `is_toc_visible = false`를 해당 subtree의 기준으로 적용한다. 제외된 노드는 렌더링 목차 번호 계산에서도 제외한다.
+
+예:
+
+```text
+Level 1: Front Matter
+  Level 2: 문서 개요
+  Level 2: 변경 이력
+  Level 2: 용어 정의
+
+Level 1: Part I
+  Level 2: Chapter 1
+```
+
+위 구조에서 Front Matter와 Body는 서로 다른 numbering policy를 가질 수 있다. Front Matter는 번호 없이 표시하고, Body는 Part/Chapter 번호를 계산할 수 있다. 번호 표시 방식은 renderer에서 지정하되, Document는 node level, sort order, visibility, numbering policy 참조를 제공한다.
+
+## 5. Heading과 Content 경계
+
+Heading 4 이하의 세부 제목은 기본적으로 Content Block 내부의 구조로 본다. 다만 문서 유형이 4단계 taxonomy를 사용하면 Level 4까지 TOC Node로 관리할 수 있다.
+
+TOC Node로 승격할지 Content 내부 heading으로 둘지는 다음 기준으로 판단한다.
+
+| 판단 질문 | TOC Node 후보 | Content 내부 heading 후보 |
+| --- | --- | --- |
+| 독자가 목차에서 직접 찾아야 하는가 | 예 | 아니오 |
+| 별도 작성, 검토, revision 대상인가 | 예 | 아니오 |
+| 하위 content와 annotation을 독립적으로 연결해야 하는가 | 예 | 아니오 |
+| 단순 문단 안의 소제목인가 | 아니오 | 예 |
+
+목차 구조를 변경하면 title, sort order, numbering, anchor, block 연결, annotation 연결, revision 영향까지 함께 확인한다.

package/agent/guides/50-content-block-guide.md

@@ -0,0 +1,57 @@
+# Content와 Typed Block 작성 기준
+
+Content는 특정 Document 또는 TOC Node에 붙는 Block Collection이다. Content는 본문을 담는 그릇이고, 작성 계획이나 논증 흐름 모델 자체가 아니다.
+
+## 1. Content와 Block
+
+| 구분 | 의미 |
+| --- | --- |
+| Content | 하나의 Document 또는 TOC Node에 연결되는 본문 block 묶음 |
+| ContentBlock | Content 안에 배치되는 하나의 typed block |
+| Block Type | paragraph, quote, table, figure, diagram, list, code, callout 등 payload schema를 결정하는 유형 |
+| Block Schema | block type별 payload 구조와 validation rule |
+| schemaRef | 특정 표준 서식이나 block payload schema를 참조하는 식별자 |
+
+Block은 하나의 표현 단위이며 작성 흐름 자체가 아니다. 참조 프로젝트의 `BlockFlow`처럼 문단, 표, 도해 배치 흐름을 설계하는 정보는 유용하지만, Document 1차 모델에서는 Content가 block collection만 가진다. 작성 흐름 계획은 Methodology, Authoring, Artifact Standard 계열에서 별도로 다룰 수 있다.
+
+## 2. Block Type별 책임
+
+| Block Type | 책임 | 사용 기준 |
+| --- | --- | --- |
+| paragraph | 하나의 판단, 근거, 정의, 예시, 검증 기준을 문장으로 설명한다. | 본문 전개의 기본 단위다. |
+| quote | 핵심 판단이나 해석 기준을 짧게 강조한다. | 후속 paragraph가 근거와 해석을 반드시 뒷받침한다. |
+| table | 비교, 분류, 평가, 매핑, 체크리스트, 절차를 구조화한다. | 본문을 대체하지 않고 판단 기준을 정렬한다. |
+| diagram | 구조, 관계, 경계, 흐름, 품질 게이트를 시각화한다. | 원천과 렌더링 결과를 구분한다. |
+| figure | 일반 이미지, 화면, 캡처, 참고 그림을 연결한다. | 공식 본문에 필요한 경우만 사용한다. |
+| list | 병렬 항목을 짧게 나열한다. | 항목 간 추상화 수준이 같아야 한다. |
+| code | 코드, 설정, 명령 예시를 제공한다. | 본문 판단을 확인하거나 적용 방법을 보여줄 때만 사용한다. |
+| callout | 주의, 제한, 예외, 확인 필요 사항을 강조한다. | 본문 판단을 대체하지 않고 영향과 조치를 이어서 설명한다. |
+
+## 3. Block 배치 기준
+
+Block은 독자가 하나의 판단 흐름을 따라가도록 배치한다. 기본 흐름은 다음 중 필요한 요소를 선택한다.
+
+```text
+정의 -> 필요성 -> 판단 기준 -> 근거 -> 예시 -> 적용 -> 검증
+```
+
+표와 도해는 본문을 대체하지 않고 본문 주장을 구조화하거나 시각화한다. 표나 도해 앞에는 목적과 읽는 기준을 두고, 뒤에는 판단 결과나 적용 의미를 설명한다.
+
+Quote와 callout은 선언으로 끝내지 않는다. 같은 Content 안에서 후속 paragraph가 근거, 설명, 예시, 확인 기준 중 필요한 항목을 제공해야 한다.
+
+## 4. Caption과 numbering
+
+Caption은 번호를 제외한 의미 제목으로 저장하고 표시 번호는 렌더링 시점에 계산한다.
+
+| 저장할 caption | 저장하지 않을 caption |
+| --- | --- |
+| 문서 산출물별 사용 기준 | 표 1-9. 문서 산출물별 사용 기준 |
+| 모듈 경계 판단 흐름 | 그림 5-2. 모듈 경계 판단 흐름 |
+
+Caption은 `표`, `그림`, `도해` 같은 일반명만 남기지 않는다. Caption만 보고도 block의 판단 대상이 드러나야 한다.
+
+Markdown Import처럼 이미 presentation된 산출물을 수집하는 경우에는 원문 표시를 추적하기 위해 `rawCaption`과 `captionNumber`를 보존할 수 있다. 이 경우에도 작성 기준의 의미 caption은 번호를 제외한 `caption` 값으로 분리한다.
+
+## 5. Source와 generated artifact 분리
+
+Block payload에는 원천 정보와 생성 결과를 구분해 저장한다. 예를 들어 diagram block은 Mermaid source, draw.io source, prompt source, rendered image path를 구분할 수 있다. rendered artifact의 품질 검증과 변환은 Render 계열 책임이다.

package/agent/guides/51-paragraph-authoring-guide.md

@@ -0,0 +1,68 @@
+# Paragraph 작성 기준
+
+한 문단은 하나의 중심 메시지만 가진다. Paragraph block은 최종 본문 문장을 담는 기본 단위이며, 작성자 메모나 작업 계획을 본문에 섞지 않는다.
+
+## 1. 문단 역할
+
+문단은 정의, 배경, 문제, 원인, 영향, 원칙, 기준, 근거, 예시, 비교, 대안, 권고, 절차, 검증, 위험, 예외, 전환, 요약 같은 역할 중 하나를 명확히 가진다.
+
+| 역할 | 목적 | 대표 문장 방향 |
+| --- | --- | --- |
+| definition | 개념 의미와 책임 범위를 고정한다. | `A는 B를 판단하기 위한 기준이다.` |
+| background | 기준이 필요한 맥락을 연다. | `A만으로는 B를 설명하기 어렵다.` |
+| problem | 기준 부재 시 발생하는 위험을 드러낸다. | `B가 없으면 C의 기준이 일관성을 잃는다.` |
+| criterion | 선택, 분류, 검증 기준을 제시한다. | `A를 판단할 때는 B, C, D를 확인한다.` |
+| evidence | 판단을 뒷받침하는 이유를 제시한다. | `이 기준이 필요한 이유는 A다.` |
+| example | 추상 기준을 실제 상황으로 구체화한다. | `예를 들어 A가 바뀌면 B를 먼저 확인한다.` |
+| validation | 확인 방법과 판정 기준을 설명한다. | `A는 B 산출물과 C 규칙으로 확인한다.` |
+| transition | 표, 도해, 후속 문단으로 논리를 넘긴다. | `다음 표는 이 기준을 확인 항목으로 정리한다.` |
+| summary | 절의 결론을 닫는다. | `결국 A는 B를 위한 기준이다.` |
+
+## 2. 기본 전개 흐름
+
+개념은 정의에서 끝내지 않고 필요성, 적용 위치, 확인 방법으로 연결한다. 권장 흐름은 다음과 같다.
+
+```text
+정의 -> 필요성 -> 기준 -> 예시 -> 적용 -> 검증
+```
+
+모든 문단이 이 순서를 모두 가져야 하는 것은 아니다. 다만 선언형 문장만 남기면 독자가 판단하거나 적용할 수 없으므로, 필요한 경우 근거, 예시, 적용, 검증 문단을 이어서 둔다.
+
+## 3. 독자 결과 기준
+
+문단은 작성자가 무엇을 설명하고 싶은지가 아니라 독자가 읽은 뒤 무엇을 이해하거나 판단해야 하는지를 기준으로 쓴다.
+
+| 독자 결과 | 문단 작성 기준 |
+| --- | --- |
+| 이해 | 용어와 책임 범위를 먼저 고정한다. |
+| 판단 | 선택 기준, 비교 기준, 제외 기준을 제시한다. |
+| 실행 | 적용 순서, 입력, 결과, 확인 대상을 제시한다. |
+| 검토 | 통과 기준, 미충족 시 조치, 증거 위치를 제시한다. |
+
+## 4. 표와 도해 연결
+
+문단 앞뒤 연결을 고려해 표, 도해, 후속 문단으로 이어지는 이유를 분명히 한다.
+
+좋은 흐름:
+
+```text
+문단: 어떤 기준으로 비교해야 하는지 설명한다.
+표: 그 기준을 행과 열로 구조화한다.
+문단: 표가 의미하는 판단 결과와 적용 조치를 설명한다.
+```
+
+나쁜 흐름:
+
+```text
+문단 없이 표만 제시한다.
+표 뒤에 해석이 없다.
+표 caption이 "표" 또는 "정리"처럼 일반명으로 끝난다.
+```
+
+## 5. 작성 금지
+
+- 입력 근거가 없는 내용을 확정 표현으로 쓰지 않는다.
+- 작업 과정, prompt, 내부 검토 방향을 최종 본문 문단에 넣지 않는다.
+- 한 문단에 정의, 문제, 예시, 예외를 모두 밀어 넣지 않는다.
+- 앞 장에서 후속 장의 상세 내용을 미리 확정하지 않는다.
+- 같은 개념에 여러 용어를 번갈아 쓰지 않는다.