@soddong/agentic-domain-methodology 0.11.1

package/.tbls.yml

@@ -0,0 +1,64 @@
+name: agentic-domain-methodology
+desc: Agentic Platform methodology domain database.
+
+dsn: ${AGENTIC_DOMAIN_METHODOLOGY_SCHEMA_DSN}
+docPath: ${AGENTIC_DOMAIN_METHODOLOGY_SCHEMA_DOC_PATH}
+
+format:
+  adjust: true
+  sort: false
+  number: false
+  hideColumnsWithoutValues: true
+
+er:
+  skip: false
+  format: svg
+  comment: true
+  hideDef: true
+  showColumnTypes:
+    related: true
+    primary: true
+  distance: 1
+
+include:
+  - methodology_*
+
+comments:
+  - table: methodology_schema_migrations
+    tableComment: methodology 패키지의 migration 적용 이력을 관리한다.
+  - table: methodology_code_groups
+    tableComment: 코드 그룹을 정의한다.
+  - table: methodology_codes
+    tableComment: 코드 그룹별 코드 값을 정의한다.
+  - table: methodology_methodologies
+    tableComment: 방법론 정의의 최상위 versioned definition을 관리한다.
+  - table: methodology_lifecycles
+    tableComment: 방법론 생명주기 모델을 관리한다.
+  - table: methodology_phases
+    tableComment: lifecycle 내 큰 구간을 관리한다.
+  - table: methodology_processes
+    tableComment: 재사용 가능한 수행 절차를 관리한다.
+  - table: methodology_phase_processes
+    tableComment: phase에서 어떤 process를 어떤 순서로 사용할지 관리한다.
+  - table: methodology_activities
+    tableComment: process 내부의 기본 수행 활동을 관리한다.
+  - table: methodology_steps
+    tableComment: activity 하위 순차 절차를 관리한다.
+  - table: methodology_stages
+    tableComment: process 내부 activity grouping, gate, 기준선, 전환 구간을 관리한다.
+  - table: methodology_stage_activities
+    tableComment: stage와 activity의 포함 관계를 관리한다.
+  - table: methodology_activity_artifact_requirements
+    tableComment: activity의 input/output/supporting 산출물 요구를 관리한다.
+  - table: methodology_stage_artifact_requirements
+    tableComment: stage gate, baseline, handoff, approval에 필요한 추가 산출물 요구를 관리한다.
+  - table: methodology_stage_criteria
+    tableComment: stage의 entry, exit, gate 판단 기준을 관리한다.
+  - table: methodology_activity_criteria
+    tableComment: activity의 completion 판단 기준을 관리한다.
+  - table: methodology_handoff_requirements
+    tableComment: phase, process, stage, activity 간 전달 요구를 관리한다.
+  - table: methodology_baseline_requirements
+    tableComment: baseline이 필요한 scope와 trigger를 관리한다.
+  - table: methodology_trace_policies
+    tableComment: 실제 trace link가 아니라 trace 필요 관계 정책을 관리한다.

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## 0.11.1
+
+- `applyAgenticSeed()`의 `criteria` section 처리에서 `scopeTypeCode = activity`를 지원한다.
+- Activity completion criteria seed를 `methodology_activity_criteria`에 저장할 수 있게 한다.
+- Stage criteria와 Activity criteria를 함께 포함하는 AI-Agent SDLC Build Planning seed 적용을 지원한다.
+
+## 0.11.0
+
+- `applyAgenticSeed()` runtime seed apply handler를 추가한다.
+- `methodology`, `lifecycle`, `phases`, `processes`, `stages`, `activities`, `activityArtifactRequirements`, `criteria`, `handoffs` seed section을 methodology DB에 적용할 수 있게 한다.
+- AI-Agent SDLC seed의 `stage_gate` handoff type은 methodology 공통 handoff type `context`로 저장하고 원본 payload는 metadata에 보존한다.
+- seed apply dev-test를 추가해 runtime이 호출하는 section 단위 handler 동작을 검증한다.
+
+## 0.10.0
+
+- Handoff Requirement public API를 추가한다.
+- `createHandoffRequirement()`, `listHandoffRequirementsBySource()`, `listHandoffRequirementsByTarget()`로 Phase/Process/Stage/Activity 간 전달 계약을 생성/조회할 수 있게 한다.
+- Handoff 1건이 다수 선행 산출물 component 세트를 후행 Stage 또는 Activity에 전달하는 사용 사례를 검증한다.
+- 4모듈 통합 검증에서 Stage Handoff가 artifact instance scope, required component codes, validation/review result refs를 포함하는지 확인한다.
+
+## 0.9.0
+
+- Stage Criteria public API를 추가한다.
+- `createStageCriteria()`와 `listStageCriteriaByStage()`로 Stage entry, exit, gate 기준을 생성/조회할 수 있게 한다.
+- `getMethodologyStructure()`의 Stage read model에 criteria 목록을 포함한다.
+- 4모듈 통합 검증에서 Stage Criteria가 entry/exit/gate 기준을 모두 포함하는지 확인한다.
+
+## 0.8.0
+
+- Activity Artifact Requirement에 `artifactComponentCode`, `artifactComponentRoleCode`, `outputUsageCode`를 추가한다.
+- Methodology Activity가 산출물 표준 전체뿐 아니라 artifact-standard의 특정 `DocumentComponent`까지 참조할 수 있게 한다.
+- output usage code 후보로 `produces`, `refines`, `reviews`, `consolidates`를 추가한다.
+- Build Planning fixture에서 `component_business_process_definition` Activity가 `appendix_l3_process` component를 산출하는 사용 사례를 검증한다.
+
+## 0.7.0
+
+- Methodology Common Blueprint Policy 최소 모델을 추가한다.
+- `methodology_common_blueprint_policies`, `methodology_common_blueprint_policy_nodes` 테이블을 추가한다.
+- 방법론 차원의 Front Matter, Back Matter, Body Policy 공통 구조 정책을 정의할 수 있게 한다.
+- 실제 산출물별 Document Blueprint, Template Slot, Table Schema, Validation Rule은 계속 `@soddong/agentic-domain-artifact-standard` 책임으로 유지한다.
+
+## 0.6.0
+
+- Artifact Standard 용어 기준에 맞춰 Methodology 산출물 요구와 handoff의 public API/DDL 명명을 정리한다.
+- `artifactStandardPackageCode` 입력/출력 속성을 `artifactStandardCode`로 변경한다.
+- SQLite 컬럼 `artifact_standard_package_code`를 `artifact_standard_code`로 변경한다.
+- npm package 의미와 도메인 Artifact Standard 의미가 혼동되지 않도록 README와 schema 문서를 정렬한다.
+
+## 0.5.1
+
+- `@soddong/agentic-capability-validation` dependency를 `^0.3.0`으로 정렬한다.
+- 기존 methodology validator helper API는 유지한다.
+
+## 0.5.0
+
+- `validateMethodologyDefinition()`과 개별 methodology validator에 scoped validation option을 추가한다.
+- `methodologyId` 또는 `methodologyCode + methodologyVersion` 기준으로 특정 방법론만 검증할 수 있게 한다.
+- 하나의 SQLite DB에 fixture, 테스트 데이터, 여러 방법론이 함께 있을 때 검증 결과가 섞이는 문제를 줄인다.
+- README에 Validation Scope 사용 예시를 추가한다.
+
+## 0.4.0
+
+- `temp/` 아래 Build Planning 방법론 정보를 기반으로 한 `seedBuildPlanningExample()` fixture API를 추가한다.
+- Build Planning Phase/Process, 4개 Stage, 대표 Activity, Step, primary output artifact requirement seed를 제공한다.
+- Cross-cutting Governance Activity를 Stage에 종속되지 않는 Process-level Activity로 seed한다.
+- seed 재실행 시 중복 생성하지 않고 기존 Methodology 구조를 반환하도록 idempotency를 보장한다.
+- README에 fixture/seed 사용 예시를 추가한다.
+
+## 0.3.0
+
+- Methodology 목록, Lifecycle/Phase/Process/Activity/Stage/Step/Artifact Requirement 조회 API를 추가한다.
+- Phase 기준 Process 조회와 Stage 기준 Activity 조회 API를 추가한다.
+- Methodology 전체 구조를 읽는 `getMethodologyStructure()` read model API를 추가한다.
+- README에 조회/탐색 API 사용 예시를 추가한다.
+
+## 0.2.1
+
+- Consumer 사용성 개선을 위해 `createProcessForLifecycle()` helper를 추가한다.
+- Phase 기준 Process 생성과 Phase 배정을 함께 처리하는 `createProcessForPhase()` helper를 추가한다.
+- `createProcess()` 호출 시 `methodologyId` 누락 오류를 DB 제약 오류가 아닌 service 입력 오류로 안내한다.
+- Process 추가 API 사용 기준과 잘못된 예시를 README에 보강한다.
+
+## 0.2.0
+
+- Methodology SQLite migration DDL과 schema 문서를 추가한다.
+- Methodology/Lifecycle/Phase/Process/Stage/Activity/Step repository와 service API를 추가한다.
+- Activity 산출물 요구사항, Stage criteria, handoff, baseline, trace policy 모델 기반을 추가한다.
+- `@soddong/agentic-capability-validation` 기반 methodology validator를 추가한다.
+
+## 0.1.0
+
+- `@soddong/agentic-domain-methodology` npm 패키지 skeleton 추가
+- Methodology 도메인 패키지 기본 metadata와 최소 public API 추가
+- README 및 docs 기본 문서 추가
+- build/typecheck/dev-test/pack dry-run 검증 경로 추가

package/README.md

@@ -0,0 +1,501 @@
+# @soddong/agentic-domain-methodology
+
+`@soddong/agentic-domain-methodology`는 Agentic Platform의 방법론 도메인 패키지입니다.
+
+이 패키지는 Methodology, Lifecycle, Phase, Process, Stage, Activity, Step, Gate, Handoff, Artifact Requirement, Common Blueprint Policy 같은 방법론 구조를 관리하기 위한 하위 도메인 패키지입니다.
+
+## 현재 범위
+
+현재는 패키지 skeleton, Continuous Publish/Delivery 기반, methodology SQLite schema migration, database helper, 핵심 Repository/Service API, Common Blueprint Policy, Activity Artifact Requirement의 artifact component 참조, Stage Criteria API, Handoff Requirement API, Build Planning fixture/seed, runtime seed apply handler, 최소 validator, scoped validation을 제공합니다. Agent contribution은 후속 iteration에서 구체화합니다.
+
+| 구분 | 상태 |
+| --- | --- |
+| 패키지 skeleton | 포함 |
+| 기본 문서 | 포함 |
+| build/typecheck | 포함 |
+| pack dry-run | 포함 |
+| 최소 public API | 포함 |
+| Methodology DB migration | 포함 |
+| Methodology database helper | 포함 |
+| Repository/Service | 핵심 생성/조회 API 포함 |
+| Common Blueprint Policy | 공통 Front/Back Matter 정책 포함 |
+| Activity Artifact Component Reference | Activity 산출물 요구가 artifact-standard의 특정 document component를 참조 가능 |
+| Stage Criteria API | Stage entry/exit/gate 기준 생성/조회 가능 |
+| Handoff Requirement API | 수행 단위 간 전달 계약 생성/조회 가능 |
+| Runtime Seed Apply Handler | AI-Agent SDLC seed의 methodology section 적용 가능 |
+| Validator | 최소 구조 정합성 검증 포함 |
+| Fixture/Seed | Build Planning 예시 포함 |
+| Agent contribution | 후속 iteration |
+| CLI | 1차 구현 제외 |
+| Adapter | 1차 구현 제외 |
+
+## 도메인 책임
+
+```text
+@soddong/agentic-domain-methodology
+  - Methodology
+  - Lifecycle
+  - Phase
+  - Process
+  - Stage
+  - Activity
+  - Step
+  - Gate
+  - Entry/Exit Criteria
+  - Handoff
+  - Baseline
+  - Artifact Requirement
+  - Common Blueprint Policy
+  - Trace Policy
+```
+
+## Activity Artifact Requirement와 Document Component 참조
+
+`methodology`는 산출물 표준 내부 구조를 직접 소유하지 않습니다. 본문, 부록, 하위 부록 같은 산출물 구성 단위는 `@soddong/agentic-domain-artifact-standard`의 `DocumentComponent`가 정의합니다.
+
+다만 Activity가 산출물 전체가 아니라 특정 구성 단위를 작성, 검토, 정제, 종합하는 경우가 있으므로 Activity Artifact Requirement는 optional component 참조를 가질 수 있습니다.
+
+```ts
+service.addActivityArtifactRequirement({
+  activityId: activity.activityId,
+  artifactStandardCode: "business_process_definition",
+  artifactStandardVersion: "1.0.0",
+  artifactComponentCode: "appendix_l3_process",
+  artifactComponentRoleCode: "APPENDIX",
+  requirementRoleCode: "output",
+  outputUsageCode: "produces",
+  isPrimary: true
+});
+```
+
+의미는 다음과 같습니다.
+
+```text
+Activity: L3 프로세스 부록 작성
+  output artifact standard: business_process_definition@1.0.0
+  output component: appendix_l3_process
+  usage: produces
+```
+
+이 구조에서 `methodology`는 "언제, 어떤 Activity가 어떤 산출물/component를 다루는가"만 정의합니다. 산출물 내부 component 구조와 물리 파일 정책은 `artifact-standard`, 실제 산출물 instance 연결은 후속 `artifact` 책임입니다.
+
+하나의 Stage에서 여러 산출물 구성 요소를 작성하는 경우에는 component별 Activity output으로 분리할 수 있습니다.
+
+```text
+Planning Phase
+  Business Architecture Planning Process
+    Stage: component_business_process_definition
+      Activity: business_process_main_document_authoring
+        output: business_process_definition@1.0.0 / main_document
+      Activity: l3_process_appendix_authoring
+        output: business_process_definition@1.0.0 / appendix_l3_process
+      Activity: scenario_appendix_authoring
+        output: business_process_definition@1.0.0 / appendix_scenario
+      Activity: l4_detail_appendix_authoring
+        output: business_process_definition@1.0.0 / appendix_l4_detail
+      Activity: business_process_definition_consolidation
+        input: main_document, appendix_l3_process, appendix_scenario, appendix_l4_detail
+        output: business_process_definition@1.0.0 / main_document
+        usage: refines
+```
+
+종합/정제처럼 여러 component를 읽고 MAIN 문서를 정제하는 작업도 Activity로 둘 수 있습니다. Stage gate/criterion은 이 Activity가 완료됐는지 판단하는 기준이고, handoff는 다음 Stage나 Process로 넘기는 관계입니다.
+
+한 산출물 구성 요소를 작성하는 내부 절차는 Step으로 표현할 수 있지만, 현재 조립 검증에서는 Step까지 세분화하지 않습니다.
+
+## Stage Criteria API
+
+Stage의 시작, 종료, 전환 판단 기준은 `methodology_stage_criteria`와 Service API로 관리합니다.
+
+```ts
+const exitCriteria = service.createStageCriteria({
+  stageId: stage.stageId,
+  criteriaTypeCode: "exit",
+  criteriaName: "필수 component 생성",
+  criteriaText: "MAIN, L3 부록, 시나리오 부록, L4 상세 부록 component가 모두 생성되어야 한다.",
+  validationRequired: true,
+  severityCode: "error",
+  sortOrder: 20,
+  metadata: {
+    criteriaCode: "exit_required_components_created"
+  }
+});
+
+const criteria = service.listStageCriteriaByStage(stage.stageId);
+console.log(criteria.map((item) => item.criteriaTypeCode));
+```
+
+구분 기준은 다음과 같습니다.
+
+| criteriaTypeCode | 의미 |
+| --- | --- |
+| `entry` | Stage 시작 전 준비 조건 |
+| `exit` | Stage 종료를 위한 산출물/구조 완성 조건 |
+| `gate` | 다음 Stage 또는 승인 전환 판단 조건 |
+
+## Handoff Requirement API
+
+Handoff는 실제 파일을 복사하거나 이동하는 기능이 아니라, 후속 Phase/Process/Stage/Activity가 입력으로 받아야 하는 산출물, 이슈, 결정, 제약 조건 등의 전달 계약입니다.
+
+다수의 선행 산출물 component를 하나의 artifact instance 묶음으로 후행 Stage에 넘기는 경우에는 Handoff 1건에 필수 component 목록을 metadata로 둡니다.
+
+```ts
+const handoff = service.createHandoffRequirement({
+  sourceScopeCode: "stage",
+  sourceRefId: businessProcessStage.stageId,
+  targetScopeCode: "stage",
+  targetRefId: informationObjectStage.stageId,
+  handoffTypeCode: "artifact",
+  handoffItemName: "A컴포넌트 비즈니스 프로세스 정의서",
+  handoffDescription: "컴포넌트 정보 객체 정의 Stage에서 참조할 비즈니스 프로세스 정의서 산출물 묶음이다.",
+  artifactStandardCode: "business_process_definition",
+  artifactStandardVersion: "1.0.0",
+  validationRequired: true,
+  sortOrder: 10,
+  metadata: {
+    handoffItemScope: "artifact_instance",
+    requiredComponentCodes: [
+      "main_document",
+      "appendix_l3_process",
+      "appendix_scenario",
+      "appendix_l4_detail"
+    ],
+    requiredResultRefs: [
+      "validation_result",
+      "review_decision"
+    ]
+  }
+});
+```
+
+후행 산출물을 LLM이 작성하는 경우 application 또는 runtime 조립 계층은 다음 순서로 context를 구성합니다.
+
+```text
+1. 후행 Activity 또는 Stage 식별
+2. target 기준 Handoff Requirement 조회
+3. handoff metadata의 required component set 확인
+4. artifact instance와 component resource link 조회
+5. ADoc document 내용 조회
+6. 후행 산출물의 artifact-standard 조회
+7. 선행 산출물 context + 후행 산출물 표준을 LLM prompt/resource context로 조립
+```
+
+조회 예:
+
+```ts
+const inboundHandoffs = service.listHandoffRequirementsByTarget(
+  "stage",
+  informationObjectStage.stageId
+);
+
+const outboundHandoffs = service.listHandoffRequirementsBySource(
+  "stage",
+  businessProcessStage.stageId
+);
+```
+
+## 제외 범위
+
+| 제외 항목 | 담당 후보 |
+| --- | --- |
+| Document 내부 구조 | `@soddong/agentic-domain-document` |
+| Artifact Standard 본문 구조 | `@soddong/agentic-domain-artifact-standard` |
+| Artifact instance | `@soddong/agentic-domain-artifact` |
+| AI-Agent SDLC seed | `@soddong/agentic-methodology-ai-agent-sdlc` |
+| Runner | `@soddong/agentic-runtime` 또는 application package |
+| Render | render capability |
+| Adapter | `@soddong/agentic-runtime` |
+
+## 명명 기준
+
+| 구분 | 기준 |
+| --- | --- |
+| logical schema | `methodology` |
+| SQLite table prefix | `methodology_` |
+| PostgreSQL mapping | 향후 중앙 DB 활용 시 `methodology.*` 후보 |
+
+## 개발 검증
+
+```bash
+npm run build --workspace @soddong/agentic-domain-methodology
+npm run typecheck --workspace @soddong/agentic-domain-methodology
+npm run dev:test:agentic-domain-methodology
+npm pack --workspace @soddong/agentic-domain-methodology --dry-run --cache /private/tmp/agentic-npm-cache
+```
+
+## 기본 API 예시
+
+```ts
+import {
+  applyAgenticSeed,
+  getMethodologyPackageInfo,
+  initializeMethodologyDatabase,
+  openMethodologyDatabase,
+  MethodologyService,
+  seedBuildPlanningExample,
+  validateMethodologyDefinition
+} from "@soddong/agentic-domain-methodology";
+
+console.log(getMethodologyPackageInfo());
+
+const result = initializeMethodologyDatabase({
+  projectRoot: process.cwd()
+});
+
+console.log(result.tables);
+
+const db = openMethodologyDatabase({ projectRoot: process.cwd() });
+const service = new MethodologyService(db);
+
+const scenario = service.createDefinitionScenario({
+  methodology: {
+    methodologyCode: "sdlc_default",
+    methodologyName: "기본 SDLC 방법론",
+    methodologyVersion: "1.0.0"
+  },
+  lifecycle: {
+    lifecycleCode: "default_lifecycle",
+    lifecycleName: "기본 Lifecycle"
+  },
+  phase: {
+    phaseCode: "analysis",
+    phaseName: "분석"
+  },
+  process: {
+    processCode: "requirements_management",
+    processName: "요구사항 관리"
+  },
+  activity: {
+    activityCode: "requirements_definition",
+    activityName: "요구사항 정의"
+  }
+});
+
+console.log(scenario.activity.activityId);
+
+const validation = validateMethodologyDefinition(db);
+console.log(validation.valid);
+db.close();
+```
+
+## Process 추가 API 사용 기준
+
+Process는 특정 Lifecycle에 직접 종속되는 데이터가 아니라 Methodology에 종속됩니다. Phase와 Process의 관계는 `methodology_phase_processes` 연결 테이블로 표현합니다.
+
+따라서 이미 생성된 Lifecycle 또는 Phase를 기준으로 Process를 추가할 때는 `createProcess()`에 `lifecycleId`를 넘기지 않습니다.
+
+잘못된 예:
+
+```ts
+service.createProcess({
+  lifecycleId: scenario.lifecycle.lifecycleId,
+  processCode: "architecture_design",
+  processName: "아키텍처 설계"
+});
+```
+
+`createProcess()`는 `methodologyId`를 직접 받는 저수준 API입니다.
+
+```ts
+service.createProcess({
+  methodologyId: scenario.methodology.methodologyId,
+  processCode: "architecture_design",
+  processName: "아키텍처 설계"
+});
+```
+
+consumer 코드에서 Lifecycle 기준으로 Process를 추가하고 싶다면 `createProcessForLifecycle()`을 사용합니다.
+
+```ts
+const process = service.createProcessForLifecycle({
+  lifecycleId: scenario.lifecycle.lifecycleId,
+  processCode: "architecture_design",
+  processName: "아키텍처 설계"
+});
+```
+
+Phase 기준으로 Process를 만들고 Phase에 바로 배정하려면 `createProcessForPhase()`를 사용합니다.
+
+```ts
+const result = service.createProcessForPhase({
+  phaseId: scenario.phase.phaseId,
+  processCode: "architecture_design",
+  processName: "아키텍처 설계",
+  phaseProcess: {
+    sortOrder: 20
+  }
+});
+
+console.log(result.process.processId);
+console.log(result.phaseProcess.phaseProcessId);
+```
+
+## 조회/탐색 API 예시
+
+생성된 방법론 구조를 확인할 때는 직접 SQL을 작성하기보다 Service 조회 API를 우선 사용합니다.
+
+단위 목록 조회:
+
+```ts
+const lifecycles = service.listLifecyclesByMethodology(scenario.methodology.methodologyId);
+const phases = service.listPhasesByLifecycle(scenario.lifecycle.lifecycleId);
+const processes = service.listProcessesByPhase(scenario.phase.phaseId);
+const activities = service.listActivitiesByProcess(scenario.process.processId);
+const stages = service.listStagesByProcess(scenario.process.processId);
+const steps = service.listStepsByActivity(scenario.activity.activityId);
+const outputs = service.listActivityArtifactRequirements(scenario.activity.activityId);
+```
+
+전체 구조 조회:
+
+```ts
+const structure = service.getMethodologyStructure(scenario.methodology.methodologyId);
+
+for (const lifecycle of structure.lifecycles) {
+  for (const phase of lifecycle.phases) {
+    for (const process of phase.processes) {
+      console.log(process.process.processName);
+      console.log(process.activities.map((item) => item.activity.activityName));
+      console.log(process.stages.map((item) => item.stage.stageName));
+    }
+  }
+}
+```
+
+`getMethodologyStructure()`는 Methodology -> Lifecycle -> Phase -> Process -> Activity/Stage 구조를 읽기 위한 편의 read model입니다. Stage 하위 Activity는 `methodology_stage_activities` 연결 기준으로 조회됩니다.
+
+## Fixture/Seed 사용 예시
+
+`seedBuildPlanningExample()`은 `temp/` 아래 Build Planning 방법론 정리 내용을 기준으로 구성한 예시 데이터를 생성합니다.
+
+포함 범위:
+
+- `Build Planning Phase`
+- `Build Planning Process`
+- `Analysis Stage`
+- `Interface Design Stage`
+- `Structure Design Stage`
+- `Build Scope Planning Stage`
+- Stage별 대표 Activity, Step, primary output artifact requirement
+- 특정 Stage에 종속되지 않는 Cross-cutting Governance Activity
+
+사용 예:
+
+```ts
+const seedResult = seedBuildPlanningExample(db);
+
+console.log(seedResult.seeded);
+console.log(seedResult.structure.methodology.methodologyName);
+console.log(seedResult.structure.lifecycles[0].phases[0].processes[0].stages.length);
+console.log(seedResult.structure.lifecycles[0].phases[0].processes[0].activities.length);
+```
+
+동일한 `methodologyCode + methodologyVersion`이 이미 존재하면 중복 생성하지 않고 기존 구조를 반환합니다.
+
+```ts
+const first = seedBuildPlanningExample(db);
+const second = seedBuildPlanningExample(db);
+
+console.log(first.seeded);  // true
+console.log(second.seeded); // false
+```
+
+## Runtime Seed Apply Handler
+
+`applyAgenticSeed()`는 `@soddong/agentic-runtime seed apply`가 target package를 호출할 때 사용하는 handler입니다.
+
+이 handler는 methodology 도메인이 소유하는 section만 처리합니다.
+
+| sourceSection | 처리 |
+| --- | --- |
+| `methodology` | Methodology 생성 또는 기존 항목 skip |
+| `lifecycle` | Lifecycle 생성 또는 기존 항목 skip |
+| `phases` | Phase 목록 생성 |
+| `processes` | Process 생성 및 Phase 연결 |
+| `stages` | Stage 목록 생성 |
+| `activities` | Activity 생성 및 Stage 연결 |
+| `activityArtifactRequirements` | Activity output/input/supporting artifact requirement 생성 |
+| `criteria` | Stage criteria 생성 |
+| `handoffs` | Stage 간 handoff requirement 생성 |
+
+`generatedOutputLinks`, `validationProfiles`, `sampleExecution`은 각각 `artifact-standard`, `validation`, `artifact` 계열 패키지의 책임입니다.
+
+예시:
+
+```ts
+await applyAgenticSeed({
+  sourcePackageName: "@soddong/agentic-methodology-ai-agent-sdlc",
+  sourcePackageVersion: "0.2.0",
+  bundleCode: "ai-agent-sdlc-build-planning",
+  bundleVersion: "0.2.0",
+  methodologyCode: "ai_agent_sdlc",
+  sourceSection: "stages",
+  targetOperation: "upsert_stages",
+  mode: "apply",
+  itemPayload: [
+    {
+      processCode: "build_planning_process",
+      stageCode: "analysis_stage",
+      stageName: "Analysis Stage",
+      stageTypeCode: "analysis",
+      stageOrder: 10
+    }
+  ]
+});
+```
+
+적용 결과는 다음 중 하나를 반환합니다.
+
+| status | 의미 |
+| --- | --- |
+| `applied` | 신규 methodology 데이터가 생성됨 |
+| `skipped` | 동일 기준의 데이터가 이미 있어 중복 생성하지 않음 |
+| `blocked` | 선행 methodology, lifecycle, phase, process, stage, activity 등이 없어 적용할 수 없음 |
+| `failed` | payload 필수값 누락 또는 DB 제약 오류 |
+
+AI-Agent SDLC seed의 `handoffTypeCode: "stage_gate"`는 현재 methodology DB의 공통 handoff type에 직접 포함되지 않으므로 `context`로 저장합니다. 원본 `stage_gate` 값은 metadata의 `seedPayload`에 보존합니다.
+
+## Validation Scope 사용 예시
+
+`validateMethodologyDefinition(db)`는 기본적으로 methodology DB 전체를 검증합니다. 하나의 consumer 프로젝트 안에 여러 방법론, 테스트 데이터, 의도적으로 만든 오류 데이터가 함께 있을 수 있으므로 특정 방법론만 검증해야 할 때는 scope를 지정합니다.
+
+방법론 ID 기준:
+
+```ts
+const result = validateMethodologyDefinition(db, {
+  scope: {
+    methodologyId: seedResult.methodologyId
+  }
+});
+
+console.log(result.valid);
+```
+
+방법론 코드와 버전 기준:
+
+```ts
+const result = validateMethodologyDefinition(db, {
+  scope: {
+    methodologyCode: "build_planning_example",
+    methodologyVersion: "1.0.0"
+  }
+});
+
+console.log(result.valid);
+```
+
+전체 validation은 DB 안의 모든 방법론과 테스트 데이터를 함께 검증합니다. 특정 fixture나 특정 방법론의 품질만 확인하려면 scoped validation을 사용합니다.
+
+기대 결과:
+
+```json
+{
+  "name": "@soddong/agentic-domain-methodology",
+  "version": "0.11.1",
+  "layer": "domain",
+  "logicalSchema": "methodology",
+  "sqliteTablePrefix": "methodology_",
+  "cli": "not-provided",
+  "adapter": "not-provided"
+}
+```

package/dist/database.d.ts

@@ -0,0 +1,8 @@
+import Database from "better-sqlite3";
+import type { MethodologyDatabaseInitResult, MethodologyDatabaseOptions } from "./types.js";
+export declare function resolveMethodologyDatabasePath(options?: MethodologyDatabaseOptions): string;
+export declare function listMethodologyTables(db: Database.Database): string[];
+export declare function applyMethodologyBaseMigration(db: Database.Database): void;
+export declare function openMethodologyDatabase(options?: MethodologyDatabaseOptions): Database.Database;
+export declare function initializeMethodologyDatabase(options?: MethodologyDatabaseOptions): MethodologyDatabaseInitResult;
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAGtC,OAAO,KAAK,EAAE,6BAA6B,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAuB5F,wBAAgB,8BAA8B,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,CAiB/F;AAOD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,EAAE,CAYrE;AAED,wBAAgB,6BAA6B,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAEzE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,0BAA+B,GAAG,QAAQ,CAAC,QAAQ,CAkBnG;AAED,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,0BAA+B,GAAG,6BAA6B,CAcrH"}