agentic-domain-document 0.6.0

package/docs/usage.md

@@ -0,0 +1,332 @@
+# agentic-domain-document 사용 매뉴얼
+
+## 1. 목적
+
+본 문서는 `agentic-domain-document` 패키지 사용자가 패키지의 책임과 현재 사용 가능 범위를 이해하기 위한 문서입니다.
+
+`Adoc`은 `agentic-domain-document`가 관리하는 Agentic Document의 공식 약칭입니다. Adoc은 Document, Node, Content, Block 단위로 관리되며, Adoc Tree와 Adoc Markdown Projection으로 조회할 수 있습니다.
+
+## 2. 현재 상태
+
+Iteration 1에서는 패키지 skeleton, Continuous Publish/Delivery 기반, Document DB schema, 최소 Repository/Service/Validator API를 제공합니다.
+
+```text
+포함:
+  - package metadata
+  - TypeScript entrypoint
+  - 기본 문서
+  - build/typecheck/pack dry-run 검증
+  - Document/TOC Node/Content/Typed Block migration
+  - repository/service/validator
+  - reader/query API
+  - table/figure/diagram 복원을 포함한 기본 Adoc Markdown Projection
+  - table/figure caption binding을 포함한 Markdown 기반 전체 문서/챕터 import
+  - fixture/dev-test
+
+제외:
+  - CLI
+  - Agent adapter
+  - 본격 Rendering lifecycle
+  - Artifact Standard 연계
+```
+
+## 3. 설치
+
+운영환경에서는 내부 NPM Registry proxy/group을 통해 설치합니다.
+
+```bash
+npm install agentic-domain-document@0.6.0
+```
+
+registry를 명시해야 하는 경우:
+
+```bash
+npm install agentic-domain-document@0.6.0 --registry=운영환경_NPM_GROUP_REGISTRY_URL
+```
+
+## 4. 기본 import 확인
+
+```ts
+import { agenticDomainDocumentPackage } from "agentic-domain-document";
+
+console.log(agenticDomainDocumentPackage.logicalSchema);
+```
+
+기대 결과:
+
+```text
+document
+```
+
+## 5. 기본 사용 흐름
+
+`agentic-domain-document`는 domain package이므로 CLI가 아니라 TypeScript API로 사용합니다.
+
+```ts
+import { createDocumentService } from "agentic-domain-document";
+
+const service = createDocumentService({
+  databasePath: ".agentic/platform.sqlite"
+});
+
+try {
+  const document = service.createDocument({
+    title: "아키텍처 명세서",
+    documentTypeCode: "architecture_specification",
+    taxonomyCode: "architecture_specification",
+    author: {
+      type: "user",
+      id: "u001",
+      name: "작성자"
+    }
+  });
+
+  const part = service.createNode({
+    documentId: document.documentId,
+    nodeLevel: 1,
+    title: "Part I"
+  });
+
+  const chapter = service.createNode({
+    documentId: document.documentId,
+    parentNodeId: part.nodeId,
+    nodeLevel: 2,
+    title: "문서 개요"
+  });
+
+  const content = service.ensureContent(chapter.nodeId);
+
+  service.addBlock({
+    contentId: content.contentId,
+    blockTypeCode: "paragraph",
+    contentText: "이 장에서는 문서의 목적과 범위를 설명합니다."
+  });
+
+  const toc = service.getDocumentToc(document.documentId);
+  const validation = service.validateDocument(document.documentId);
+
+  console.log(toc);
+  console.log(validation.valid);
+} finally {
+  service.close();
+}
+```
+
+## 6. 상태 전이와 version snapshot
+
+문서 상태 전이는 Service API에서 수행합니다.
+
+```ts
+service.requestReview({
+  documentId,
+  reason: "검토 요청",
+  versionLabel: "0.1-review"
+});
+
+service.approveDocument({
+  documentId,
+  reason: "검토 완료",
+  versionLabel: "0.1-approved"
+});
+
+service.publishDocument({
+  documentId,
+  reason: "배포 승인",
+  versionLabel: "1.0.0"
+});
+```
+
+`draft` 상태의 변경은 revision/event를 남기지 않습니다. `in_review` 이후 상태 전이와 annotation 처리는 revision/event/version으로 기록합니다.
+
+`approved` 또는 `published` 문서를 수정해야 할 경우 직접 수정하지 않고 새 draft를 생성합니다.
+
+```ts
+const draft = service.createDraftFromDocument({
+  sourceDocumentId: publishedDocumentId,
+  title: "아키텍처 명세서 개정 초안",
+  versionLabel: "1.1-draft"
+});
+```
+
+Revision, change event, version, annotation 관련 일시 컬럼은 프로젝트 공통 시간 처리 기준을 따릅니다.
+
+```text
+- DB 저장 기준은 UTC입니다.
+- SQLite timezone 없는 DATETIME 문자열은 UTC로 해석합니다.
+- 사용자에게 표시하는 변경 일시와 문서 이력 일시는 기본 KST 기준입니다.
+- 일자 단위 문서 이력 조회가 필요하면 KST calendar boundary를 UTC SQL boundary로 변환해 조회합니다.
+```
+
+## 7. CLI 기준
+
+## 7. Adoc 조회와 Markdown Projection
+
+Adoc 조회는 직접 SQL보다 `DocumentReader`를 우선 사용합니다.
+
+```ts
+import { createDocumentReader } from "agentic-domain-document";
+
+const reader = createDocumentReader({
+  databasePath: ".agentic/platform.sqlite"
+});
+
+try {
+  const document = reader.getLatestDocument({
+    documentTypeCode: "architecture_specification"
+  });
+
+  if (document !== undefined) {
+    const tree = reader.getDocumentTree(document.documentId);
+    const matches = reader.findBlocks(document.documentId, {
+      contains: "Contract API"
+    });
+    const markdown = reader.toMarkdown(document.documentId, {
+      includeFrontmatter: true,
+      includeNodeAnchors: true,
+      includeBlockAnchors: true
+    });
+
+    console.log(tree);
+    console.log(matches);
+    console.log(markdown);
+  }
+} finally {
+  reader.close();
+}
+```
+
+Adoc Markdown Projection은 조회용 파생물입니다.
+
+```text
+- source of truth는 Adoc의 Document/Node/Content/Block 상태입니다.
+- Markdown Projection을 직접 수정하지 않습니다.
+- 수정은 DocumentService 또는 후속 DocumentWriter API로 수행합니다.
+- 수정 후 Projection을 다시 생성해 확인합니다.
+- Projection은 table, figure, diagram block을 기본 Markdown으로 복원합니다.
+- Markdown/PDF/PPTX/HTML render lifecycle은 agentic-capability-render 책임입니다.
+```
+
+## 8. CLI 기준
+
+## 8. Adoc Markdown Import
+
+Adoc 작성의 1차 import 대상은 Markdown입니다. Markdown Import는 전체 문서 생성과 챕터 append를 지원합니다.
+
+```ts
+import { createDocumentMarkdownImporter } from "agentic-domain-document";
+
+const importer = createDocumentMarkdownImporter({
+  databasePath: ".agentic/platform.sqlite"
+});
+
+try {
+  const documentResult = importer.importMarkdownDocument({
+    title: "아키텍처 명세서",
+    documentTypeCode: "architecture_specification",
+    taxonomyCode: "architecture_specification",
+    markdown,
+    sourcePath: "chapters/chapter-01.md",
+    policy: {
+      validateAfterImport: true
+    }
+  });
+
+  importer.importMarkdownChapter({
+    documentId: documentResult.document.documentId,
+    markdown: chapterMarkdown,
+    sourcePath: "chapters/chapter-02.md",
+    policy: {
+      validateAfterImport: true
+    }
+  });
+} finally {
+  importer.close();
+}
+```
+
+Markdown Import 기준:
+
+```text
+- import 결과는 draft Adoc으로 관리합니다.
+- import는 Document/Node/Content/Block을 생성합니다.
+- sourcePath와 source line metadata를 node/block metadata에 남깁니다.
+- `표 N. 제목 - 요약` caption은 다음 Markdown table block에 결합합니다.
+- image alt 또는 visible `그림 N. 제목 - 요약` caption은 figure block에 결합합니다.
+- image alt와 visible caption이 동일하면 visible caption을 별도 paragraph로 import하지 않습니다.
+- mermaid/plantuml fenced code는 diagram block으로 import합니다.
+- import 후 validateDocument를 실행할 수 있습니다.
+- BlockFlow YAML, PDF/PPTX/HTML, merge/reconcile은 1차 범위에서 제외합니다.
+```
+
+참조 아키텍처 명세서 Markdown import 검증:
+
+```bash
+npm run dev:test:agentic-domain-document:reference-markdown
+```
+
+## 9. CLI 기준
+
+`agentic-domain-document`는 domain package이므로 Iteration 1에서는 별도 CLI를 제공하지 않습니다.
+
+CLI가 필요한 기능은 후속 iteration에서 application package 또는 runtime command로 노출할지 검토합니다.
+
+## 10. Document Agent 리소스
+
+`agentic-domain-document`는 문서 작성 agent가 사용할 resource contribution을 제공합니다.
+
+```ts
+import { documentAgentContribution } from "agentic-domain-document";
+
+console.log(documentAgentContribution.manifest.agentId);
+console.log(documentAgentContribution.resourceIndex?.instructions.length);
+```
+
+Agent manifest, routing, capability, resource index, instruction, guide, example, validation rule, source mapping은 TypeScript inline 문자열이 아니라 `agent/` 리소스를 원천으로 관리합니다.
+
+```text
+agent/
+  agent.manifest.json
+  routing.json
+  resource-index.json
+  capabilities/
+    document-authoring.json
+    document-block.json
+    document-toc.json
+    document-validation.json
+  instructions/
+    00-runtime-behavior.md
+    10-scope-and-boundary.md
+    20-task-procedures.md
+    30-must-and-must-not.md
+  guides/
+    10-document-authoring-guide.md
+    20-domain-boundary-guide.md
+    30-authoring-policy-guide.md
+    40-toc-authoring-guide.md
+    50-content-block-guide.md
+    51-paragraph-authoring-guide.md
+    52-table-authoring-guide.md
+    53-diagram-figure-authoring-guide.md
+    70-korean-writing-style-guide.md
+  validation/
+    document-validation-rules.md
+  examples/
+    examples.md
+    document-quality-examples.md
+  sources/
+    reference-mapping.md
+```
+
+TS contribution은 `agent/` 리소스를 로드하고 export합니다. Runtime/router는 manifest를 기준으로 agent를 선택하고, 선택된 contribution의 instruction, guide, example, validation rule, source mapping을 resource index 기준으로 조립할 수 있습니다.
+
+`resource-index.json`의 `resourceGroups.order`는 리소스 분류 간 적용 순서를 나타냅니다.
+
+| 순서 | 분류 | 의미 |
+| --- | --- | --- |
+| 1 | instruction | Agent가 반드시 따르는 작동 규칙 |
+| 2 | guide | 작성 품질을 높이는 상세 기준 |
+| 3 | example | 좋은 예, 나쁜 예, payload 예시 |
+| 4 | validation_rule | 기계적으로 검증 가능한 기준 |
+| 5 | source_mapping | 규칙의 출처와 반영 근거 |
+
+각 분류 안의 개별 파일 순서는 각 resource의 `priority`로 관리합니다.

package/docs/validation-rules.md

@@ -0,0 +1,69 @@
+# agentic-domain-document Validation Rules
+
+## 1. 목적
+
+본 문서는 `agentic-domain-document`의 validator가 확인하는 rule을 설명합니다.
+
+Validator는 DB 제약조건만으로 표현하기 어려운 문서 도메인 규칙을 확인합니다. DB는 기본 무결성, 타입, JSON 유효성, FK를 담당하고, validator는 taxonomy, TOC 정책, block payload 구조 같은 도메인 규칙을 담당합니다.
+
+## 2. Rule 목록
+
+| Rule ID | Severity | 대상 | 설명 |
+| --- | --- | --- | --- |
+| `DOCUMENT.EXISTS` | error | document | 검증 대상 문서가 존재해야 합니다. |
+| `DOCUMENT.NODE.TAXONOMY_LEVEL` | error | node | node level은 문서 taxonomy에 정의되어 있어야 합니다. |
+| `DOCUMENT.NODE.PARENT_EXISTS` | error | node | parent node가 지정된 경우 실제 parent node가 존재해야 합니다. |
+| `DOCUMENT.NODE.PARENT_LEVEL` | error | node | 하위 node level은 상위 node level보다 커야 합니다. |
+| `DOCUMENT.TOC.EXCLUDED_ANCESTOR` | error | node | 상위 node가 TOC에서 제외된 경우 하위 node만 TOC에 포함할 수 없습니다. |
+| `DOCUMENT.BLOCK.TEXT_REQUIRED` | error | block | `paragraph`, `quote`, `code`, `callout` block은 `contentText`가 필요합니다. |
+| `DOCUMENT.BLOCK.JSON_REQUIRED` | error | block | `table`, `figure`, `diagram`, `list` block은 `contentJson`이 필요합니다. |
+| `DOCUMENT.BLOCK.DIAGRAM_NOTATION` | error | block | `diagram` block은 `mermaid`, `plantuml`, `drawio`, `svg` 중 하나의 notation이 필요합니다. |
+| `DOCUMENT.BLOCK.DIAGRAM_SOURCE` | error | block | `diagram` block은 `sourceText`, `sourcePath`, `path` 중 하나가 필요합니다. |
+| `DOCUMENT.BLOCK.TABLE_COLUMNS` | error | block | `table` block은 하나 이상의 column이 필요합니다. |
+| `DOCUMENT.BLOCK.TABLE_ROWS` | error | block | `table` block은 rows 배열이 필요합니다. |
+| `DOCUMENT.BLOCK.TABLE_CAPTION` | warning | block | `table` block에 caption이 없으면 경고합니다. |
+| `DOCUMENT.BLOCK.FIGURE_SOURCE` | error | block | `figure` block은 `sourcePath` 또는 `path`가 필요합니다. |
+| `DOCUMENT.BLOCK.FIGURE_CAPTION` | warning | block | `figure` block에 caption 또는 altText가 없으면 경고합니다. |
+| `DOCUMENT.BLOCK.LIST_DEPTH` | error | block | `list` block의 중첩 깊이는 3을 넘을 수 없습니다. |
+
+## 3. 적용 방식
+
+Service API 사용자는 다음 방식으로 문서 전체 정합성을 확인합니다.
+
+```ts
+const validation = service.validateDocument(documentId);
+
+if (!validation.valid) {
+  console.log(validation.issues);
+}
+```
+
+반환 형식:
+
+```ts
+interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+}
+
+interface ValidationIssue {
+  ruleId: string;
+  severity: "error" | "warning";
+  targetType: "document" | "node" | "content" | "block" | "annotation";
+  targetId: string;
+  message: string;
+  details?: unknown;
+}
+```
+
+## 4. 제외 범위
+
+Iteration 1 validator는 다음을 강하게 검증하지 않습니다.
+
+| 제외 항목 | 사유 |
+| --- | --- |
+| `schemaRef` 대상 존재 여부 | `artifact-standard` 패키지 미구현 상태에서 강결합을 피합니다. |
+| table column schema 상세 검증 | column/row 존재 여부만 확인하고 상세 schema는 산출물 서식 표준 패키지에서 담당할 가능성이 큽니다. |
+| caption 번호 계산 | rendering 단계에서 표시 정책으로 처리합니다. |
+| render 결과 검증 | render capability의 책임입니다. |
+| full diff 정합성 | document domain은 revision/event/version anchor만 관리합니다. |

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agentic-domain-document",
+  "version": "0.6.0",
+  "description": "Agentic Platform document domain package",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "agent",
+    "README.md",
+    "CHANGELOG.md",
+    ".tbls.yml",
+    "docs",
+    "src/database/migrations"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "agentic-capability-agent-client": "^0.4.0",
+    "better-sqlite3": "^12.11.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13"
+  }
+}