agentic-domain-artifact-standard

agentic-domain-artifact-standard는 Agentic Platform의 산출물 표준 도메인 패키지입니다.

이 패키지는 산출물 유형별 Artifact Standard, 템플릿, 가이드, 예시, Document Blueprint, Blueprint Node, Template Slot, Component Binding, Block/Table Schema, Validation Rule 같은 재사용 가능한 산출물 작성 기준을 소유합니다.

용어 기준

Artifact Standard는 특정 산출물 유형을 작성, 검토, 검증하기 위한 복합 표준 단위입니다. 템플릿, 가이드, 예시, 문서 blueprint, blueprint node, template slot, component binding, block/table schema, validation rule, LLM 보충 지침을 하나의 표준으로 묶어 관리합니다.

Package라는 용어는 npm 배포 단위 또는 repository package를 의미할 때만 사용합니다. 도메인 개념에는 Artifact Standard Package 대신 Artifact Standard를 사용합니다.

현재 public API에는 호환성을 위해 getArtifactStandardPackageInfo(), artifactStandardPackageCode 같은 legacy alias도 남아 있습니다. 신규 사용자는 getArtifactStandardInfo(), artifactStandardCode 계열을 우선 사용합니다.

Profile 용어 구분

artifact-standard에서 사용하는 profile 관련 용어는 다음처럼 구분합니다.

| 용어 | 소유/위치 | 의미 | 현재 상태 | | --- | --- | --- | --- | | ArtifactStandardProfile | artifact-standard 후보 모델 | 하나의 산출물 표준 안에서 복수 작성 모드나 tailoring variant를 별도 모델로 관리하는 개념 | 1차 핵심 모델에서 제외 | | DocumentImportProfile | agentic-domain-document contract | document importer가 산출물 표준의 blueprint, TOC, caption, table/figure/diagram 기준을 적용할 수 있게 받는 입력 profile | 제공/연계 | | ValidationProfile | agentic-contract-validation contract | validation rule bundle/provider profile | provider manifest로 export |

따라서 artifact-standard가 DocumentImportProfile과 validation provider profile을 제공한다고 해서 ArtifactStandardProfile DB 모델을 도입한 것은 아닙니다.

현재 범위

Iteration 0에서는 패키지 skeleton과 Continuous Publish/Delivery 기반을 제공했습니다. 현재는 1차 보강으로 agentic-domain-document의 DocumentImportProfile contract와 정렬되는 profile provider, SQLite 기반 artifact-standard repository/service, Business Process Definition fixture, Information Object Definition fixture, validation provider manifest export, Generated Output Link, runtime seed apply handler를 제공합니다. 0.10.0에서는 후행 산출물 작성 context 검증을 위해 [email protected] 표준 fixture를 추가했고, 0.10.1에서는 ArtifactStandard / artifactStandardCode 계열 호환 alias를 추가했습니다. 0.11.0에서는 AI-Agent SDLC seed의 generatedOutputLinks section을 artifact-standard DB에 적용할 수 있게 했습니다. Validator 실행 engine은 agentic-capability-validation 책임이며, artifact-standard는 검증 기준을 contract-compatible manifest로 제공하는 데 집중합니다.

| 구분 | 상태 | | --- | --- | | 패키지 skeleton | 포함 | | 기본 문서 | 포함 | | build/typecheck | 포함 | | 최소 public API | 포함 | | Architecture Specification DocumentImportProfile fixture | 포함 | | Blueprint node model | 포함 | | Template slot model | 포함 | | Component binding model | 포함 | | Document component model | 포함 | | Document component relation model | 포함 | | Physical structure policy model | 포함 | | Artifact Standard DB migration | 포함 | | Repository/Service | 포함 | | Aggregate 조회 API | 포함 | | Business Process Definition fixture helper | 포함 | | Information Object Definition fixture helper | 포함 | | Aggregate 기반 DocumentImportProfile 생성 helper | 포함 | | Generated Output Link model | 포함 | | Runtime Seed Apply Handler | generatedOutputLinks section 처리 | | Validation rule set contract export | 포함 | | Validation contract code guard | 포함 | | Validator 실행 engine | 제외: agentic-capability-validation 책임 | | Seed/Fixture | 포함 | | Agent contribution | 후속 iteration | | CLI | 1차 구현 제외 | | Adapter | 1차 구현 제외 |

도메인 책임

agentic-domain-artifact-standard
  - Artifact Standard
  - Artifact Type
  - Concept Document reference
  - Template Document reference
  - Guide Document reference
  - Example Document reference
  - Component Binding
  - Document Component
  - Document Component Relation
  - Physical Structure Policy
  - Document Blueprint
  - Blueprint Node
  - Template Slot
  - Block/Table Schema
  - Validation Rule reference
  - Generated Output Link
  - Input/Output Contract
  - Handoff Criteria

제외 범위

| 제외 항목 | 담당 후보 | | --- | --- | | 실제 산출물 instance | agentic-domain-artifact | | Document 저장 구조 | agentic-domain-document | | Methodology Activity/Stage 요구 관계 | agentic-domain-methodology | | Validation contract | agentic-contract-validation | | 검증 실행 엔진 | agentic-capability-validation | | Render 실행 | agentic-capability-render |

기본 API 예시

현재 API는 이전 호환성을 유지합니다. 도메인 용어 기준은 Artifact Standard이며, 신규 호출은 artifactStandardCode를 사용합니다.

import {
  createDocumentImportProfileFromArtifactStandardAggregate,
  getArtifactStandardDocumentProfile,
  getArtifactStandardInfo
} from "agentic-domain-artifact-standard";

console.log(getArtifactStandardInfo());

const profile = getArtifactStandardDocumentProfile({
  artifactStandardCode: "architecture_specification"
});

console.log(profile.profileCode);

Document Profile Provider

agentic-domain-artifact-standard는 document DB를 직접 조작하지 않습니다. 산출물 표준 관점에서 문서 유형별 profile을 제공하고, consumer 또는 integration layer가 이 profile을 agentic-domain-document importer에 전달합니다.

artifact-standard
  -> getArtifactStandardDocumentProfile()
  -> DocumentImportProfile
  -> document importer

getArtifactStandardDocumentProfile()은 호환성을 위해 유지되는 legacy fixture provider입니다. 신규 산출물 표준은 DB aggregate에서 document profile을 도출하는 방식을 우선 사용합니다.

const aggregate = service.getArtifactStandardAggregateByCodeVersion(
  "business_process_definition",
  "1.0.0"
);

if (aggregate !== undefined) {
  const profile = createDocumentImportProfileFromArtifactStandardAggregate(aggregate);
  console.log(profile.profileCode);
}

현재 legacy fixture로 제공되는 profile은 [email protected]입니다.

| 항목 | 값 | | --- | --- | | profile code | architecture_specification | | document type | architecture_specification | | taxonomy code | architecture_specification | | TOC level limit | 4 | | caption policy | 표, Table, 그림, Figure caption binding | | table/figure caption | required policy |

SQLite Repository / Service

agentic-domain-artifact-standard는 SQLite에서 artifact_standard_ prefix table을 사용합니다.

import {
  ArtifactStandardService,
  openArtifactStandardDatabase
} from "agentic-domain-artifact-standard";

const db = openArtifactStandardDatabase();
const service = new ArtifactStandardService(db);

const standard = service.createArtifactStandard({
  artifactStandardCode: "business_process_definition",
  artifactStandardVersion: "1.0.0",
  artifactStandardName: "Business Process Definition"
});

Validation rule set은 agentic-contract-validation과 정렬되는 provider manifest로 export할 수 있습니다.

const manifest = service.exportValidationProviderManifest(standard.artifactStandardId);
console.log(manifest.profiles);

여러 하위 구성을 한 번에 조회해야 하면 aggregate API를 사용합니다.

const aggregate = service.getArtifactStandardAggregateByCodeVersion(
  "business_process_definition",
  "1.0.0"
);

console.log(aggregate?.components);
console.log(aggregate?.componentBindings);
console.log(aggregate?.blueprints[0]?.blueprintNodes);
console.log(aggregate?.blueprints[0]?.templateSlots);
console.log(aggregate?.documentComponents);
console.log(aggregate?.documentComponentRelations);
console.log(aggregate?.physicalStructurePolicies);
console.log(aggregate?.tableSchemas[0]?.columns);
console.log(aggregate?.validationRuleSets[0]?.rules);

Generated Output Link

Generated Output Link는 산출물 표준을 기준으로 후속 산출물 또는 코드/파일 같은 생성 출력물을 만들 수 있다는 관계를 정의합니다.

예를 들어 AI-Agent SDLC Build Planning seed에서는 다음 관계를 표현합니다.

컴포넌트 모듈 구조 정의서
  -> 컴포넌트 모듈 구조 설계서

컴포넌트 모듈 구조 설계서
  -> 컴포넌트, 서브컴포넌트, 비즈니스 모듈 생성

첫 번째는 target이 다른 Artifact Standard이고, 두 번째는 target이 산출물 문서가 아니라 생성 출력물입니다.

const source = service.createArtifactStandard({
  artifactStandardCode: "component_module_structure_design",
  artifactStandardVersion: "1.0.0",
  artifactStandardName: "컴포넌트 모듈 구조 설계서"
});

service.addGeneratedOutputLink({
  linkCode: "gen_module_structure_design_to_modules",
  sourceArtifactStandardId: source.artifactStandardId,
  sourceArtifactStandardCode: source.artifactStandardCode,
  sourceArtifactStandardVersion: source.artifactStandardVersion,
  targetTypeCode: "GENERATED_OUTPUT",
  targetOutputName: "컴포넌트, 서브컴포넌트, 비즈니스 모듈 생성",
  generationModeCode: "AUTOMATIC",
  sortOrder: 20
});

applyAgenticSeed()는 agentic-runtime seed apply에서 generatedOutputLinks section을 전달받아 이 모델에 저장합니다. seed에 등장한 source 또는 target artifact standard의 상세 구조가 아직 없으면 최소 stub standard를 생성하고, 원본 seed payload는 metadata에 보존합니다.

Document Component와 Physical Structure Policy

DocumentComponent는 산출물 표준에서 본문, 부록, 보조자료 같은 문서 구성 단위를 정의합니다. 이는 guide, format, example 같은 resource component와 다릅니다.

DocumentComponent.blueprintId는 해당 component가 따라야 하는 document structure 기준을 가리킵니다. 본문과 부록이 같은 문서 저장 모델을 사용하더라도, 실제 목차와 필수 block 구조는 component별 blueprint로 다르게 정의할 수 있습니다.

예를 들어 Business Process Definition은 다음처럼 논리적으로 계층화할 수 있습니다.

main_document
  appendix_l3_process
    appendix_scenario
      appendix_l4_detail

Business Process Definition fixture는 다음처럼 component별 blueprint를 분리합니다.

| document component | blueprint | | --- | --- | | main_document | main_document | | appendix_l3_process | l3_process_appendix | | appendix_scenario | scenario_appendix | | appendix_l4_detail | l4_detail_appendix |

이 논리 구조는 parentDocumentComponentId와 DocumentComponentRelation으로 관리합니다. 반면 실제 파일 위치는 PhysicalStructurePolicy가 결정합니다.

const main = service.addDocumentComponent({
  artifactStandardId: standard.artifactStandardId,
  documentComponentCode: "main_document",
  documentComponentName: "Business Process Definition Main Document",
  componentRoleCode: "MAIN",
  componentTypeCode: "MAIN_DOCUMENT",
  logicalLevel: 0
});

const appendix = service.addDocumentComponent({
  artifactStandardId: standard.artifactStandardId,
  parentDocumentComponentId: main.documentComponentId,
  documentComponentCode: "appendix_l3_process",
  documentComponentName: "L3 Process Appendix",
  componentRoleCode: "APPENDIX",
  componentTypeCode: "L3_PROCESS_APPENDIX",
  logicalLevel: 1,
  isRepeatable: true
});

service.addDocumentComponentRelation({
  artifactStandardId: standard.artifactStandardId,
  sourceDocumentComponentId: main.documentComponentId,
  targetDocumentComponentId: appendix.documentComponentId,
  relationTypeCode: "CONTAINS",
  isRequired: true
});

service.addPhysicalStructurePolicy({
  artifactStandardId: standard.artifactStandardId,
  policyCode: "grouped_by_parent",
  policyName: "Group Appendix Documents By Parent Component",
  strategyCode: "GROUPED_BY_PARENT",
  relationSourceCode: "DB",
  pathPattern: "business-process-definition/{parentComponentCode}/{documentComponentCode}.md",
  isDefault: true
});

이 구조의 목적은 논리 구조는 계층으로 유지하되, 물리 구조는 표준 정의에 따라 계층형 폴더, level별 그룹, parent별 그룹, manifest 기반 단일 폴더 중 선택할 수 있게 하는 것입니다.

Methodology 연결 기준

artifact-standard는 산출물 내부 구조를 정의하고, methodology는 어떤 Stage/Activity에서 어떤 산출물 표준과 document component를 입력/출력으로 요구하는지 정의합니다.

비즈니스 프로세스 정의서 예시는 다음 기준으로 해석합니다.

Planning Phase
  - 컴포넌트 비즈니스 프로세스 정의 Stage
    - 비즈니스 프로세스 정의서 본문 작성 Activity
    - L3 프로세스 부록 작성 Activity
    - 시나리오 부록 작성 Activity
    - L4 상세 부록 작성 Activity
    - 본문/부록 종합 및 정제 Activity
  - 컴포넌트 정보 객체 정의 Stage
    - 선행 비즈니스 프로세스 정의서 묶음을 handoff 입력으로 사용

작성 절차의 세부 작업은 Step으로 볼 수 있지만, 현재 MVP에서는 Step 실행까지 시스템화하지 않습니다. Stage 안에서 산출물 또는 document component 단위 산출물을 생산해야 하면 Activity output으로 표현하고, 실제 산출물 instance와 ADoc document 연결은 agentic-domain-artifact와 agentic-domain-document 조립 책임으로 둡니다.

Component binding은 guide, example, LLM supplement 같은 component를 특정 구조 요소에 연결합니다.

const bindings = service.listComponentBindingsByTarget(
  aggregate.standard.artifactStandardId,
  "TABLE_SCHEMA",
  "l4_processes"
);

console.log(bindings[0]?.bindingRoleCode);

Validation rule set rule의 validationTypeCode, executionModeCode, severityCode는 agentic-contract-validation의 code guard로 검증됩니다.

appliesToTypeCode는 agentic-contract-validation에서는 domain-neutral string이지만, artifact-standard는 자기 domain target type을 별도로 관리합니다.

1차 validation target type 후보:

ARTIFACT_STANDARD
DOCUMENT_BLUEPRINT
BLUEPRINT_NODE
TEMPLATE_SLOT
TABLE_SCHEMA
TABLE_COLUMN_SCHEMA
FIGURE_POLICY
DIAGRAM_POLICY
COMPONENT
COMPONENT_BINDING
VALIDATION_RULE_SET
DOCUMENT_COMPONENT
DOCUMENT_COMPONENT_RELATION
PHYSICAL_STRUCTURE_POLICY

대표 parameter convention:

{
  "requiredColumns": ["sequence_no", "process_id"],
  "requiredBindingRoleCodes": ["PRIMARY_GUIDE"]
}

예를 들어 TABLE_SCHEMA:l4_processes에 PRIMARY_GUIDE binding이 필요한지는 다음 rule로 표현합니다.

ruleId: ARTIFACT_STANDARD.COMPONENT_BINDING.REQUIRED_ROLE
appliesToTypeCode: TABLE_SCHEMA
appliesToRef: l4_processes
parameters.requiredBindingRoleCodes: [PRIMARY_GUIDE]

Fixture Helper

사용성 테스트와 integration test를 위해 축소 fixture helper를 제공합니다.

import { seedBusinessProcessDefinitionArtifactStandard } from "agentic-domain-artifact-standard";

const fixture = seedBusinessProcessDefinitionArtifactStandard(service);
console.log(fixture.aggregate.standard.artifactStandardCode);

fixture는 실제 참조 데이터 이행이 아니라 대표 사용 사례 검증용 축소 샘플입니다.