@neobiotechlabs/neobiotech-dev-agent 0.1.14 → 0.1.16

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
         "source": "npm",
         "package": "@neobiotechlabs/neobiotech-dev-agent",
         "registry": "https://registry.npmjs.org",
-        "version": "0.1.14"
+        "version": "0.1.16"
       },
       "description": "의료기기 SW 규제 개발 자동화 (Jira·Confluence·Risk·CVSS·Xray·IEC 62304/62366·MDR·문서 렌더)",
       "category": "medical-device",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "neobiotech-dev-agent",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "displayName": "NeoBiotech Dev Agent (MedDev)",
   "description": "의료기기 SW 규제 개발 자동화 — Jira·Confluence·Risk·CVSS·Xray·IEC 62304/62366·MDR·문서 렌더",
   "author": {

package/README.md

@@ -180,7 +180,7 @@ node ~/.claude/plugins/cache/neobiotech/neobiotech-dev-agent/<version>/dist/inde
 | `401`/`403` | 토큰/권한. Jira API 토큰 재발급, 프로젝트 권한·이슈타입 존재 여부 확인 |
 | 프로젝트 키가 인식 안 됨 | `jira_init_project` 미실행. consumer `CLAUDE.md`에 키가 있는지 확인 |
 
-## 툴 목록 (54개)
+## 툴 목록 (55개)
 
 ### Jira 기본 CRUD (12)
 
@@ -210,7 +210,7 @@ node ~/.claude/plugins/cache/neobiotech/neobiotech-dev-agent/<version>/dist/inde
 | `confluence_delete_page` | 페이지 삭제 |
 | `confluence_get_spaces` | 스페이스 목록 |
 | `confluence_get_page_children` | 하위 페이지 조회 |
-| `confluence_publish_doc` | **(High-level)** 마크다운 문서 → Confluence 페이지 게재 (create/update 자동 분기, 마크다운 → storage 변환 + 코드펜스 → 코드 매크로) |
+| `confluence_publish_doc` | **(High-level)** 마크다운 문서(`markdown` 또는 `markdown_file`) → Confluence 페이지 게재 (create/update 자동 분기, 마크다운 → storage 변환 + 코드펜스 → 코드 매크로). 큰 문서(25KB+)는 `markdown_file` 권장 |
 
 ### Risk Management (5)
 
@@ -313,9 +313,17 @@ IEC 62304 추적성 관리.
 
 | 툴 | 설명 |
 |-----|------|
-| `markdown_to_pdf` | 마크다운 → PDF 변환 (시스템 폰트 자동 감지, 표지·머리말/꼬리말 옵션). base64 또는 tmpfile 출력. |
+| `markdown_to_pdf` | 마크다운(`markdown` 또는 `markdown_file`) → PDF 변환 (시스템 폰트 자동 감지, 표지·머리말/꼬리말 옵션). base64 또는 tmpfile 출력. |
 | `jira_attach_file` | Jira 이슈에 파일 첨부 (file_path 또는 base64, 50MB warning / 100MB hard limit). |
-| `jira_attach_pdf_from_markdown` | 마크다운 → PDF → Jira 첨부 원샷 (description 미수정, summary 코멘트 옵션). |## MDR 전문가 에이전트 (subagent)
+| `jira_attach_pdf_from_markdown` | 마크다운(`markdown` 또는 `markdown_file`) → PDF → Jira 첨부 원샷 (description 미수정, summary 코멘트 옵션). 큰 문서는 `markdown_file` 권장 |
+
+### 문서 리뷰 (1)
+
+| 툴 | 설명 |
+|-----|------|
+| `review_get_criteria` | 문서 리뷰 평가 기준 로드 — plugin 번들 generic 기본 + consumer cwd `data/review-criteria.md` override (2계층). `document-content-reviewer`·`requirement-coverage-tracker` subagent가 절차 첫 단계로 호출 |
+
+## MDR 전문가 에이전트 (subagent)
 
 역할별 규제 검토는 전문가 **subagent**가 담당합니다. consumer가 명시적으로 dispatch해야 동작합니다 (자동 트리거 없음):
 

package/agents/document-content-reviewer.md

@@ -0,0 +1,77 @@
+---
+name: document-content-reviewer
+description: Jira description / 첨부 본문의 LLM 자유 평가. Complete(필수 섹션 존재 + placeholder 잔존 없음) / Consistent(섹션 간 모순 부재) / Template-conformant(issuetype 템플릿 구조 준수). 문서 작성 완료·게재 직전·리뷰 시점에 사용. (레이어 ③ — soft verdict)
+tools:
+  - mcp__neobiotech-dev-agent__review_get_criteria
+  - mcp__neobiotech-dev-agent__jira_get_issue
+  - mcp__neobiotech-dev-agent__jira_get_links
+  - mcp__neobiotech-dev-agent__jira_search
+  - mcp__neobiotech-dev-agent__confluence_get_page
+  - mcp__neobiotech-dev-agent__doc_check_completeness
+  - Read
+  - Grep
+  - Glob
+model: inherit
+---
+
+# Document Content Reviewer
+
+당신은 의료기기 소프트웨어 문서 품질 평가자입니다. 평가 기준은 **`data/review-criteria.md`**(layer ② 자유 텍스트 기준)을 따릅니다. layer-1 툴(`doc_check_completeness`, `traceability_check`)은 **structural 체크만** 하므로 본 에이전트는 그것이 못 잡는 **내용 평가**(complete/consistency/template-conformance)를 담당합니다.
+
+## 수행 절차 (반드시 이 순서)
+
+1. **평가 기준 로드** — `review_get_criteria` 툴을 호출해 plugin 번들의 **generic 기본 기준**(의료기기 표준 기반)을 로드. 그 후 consumer cwd의 `data/review-criteria.md`가 **별도 존재**하면(프로젝트 오버라이드 — DYN 특정 용어·커스텀 템플릿 등) 추가로 Read해 generic 기준 위에 덮어쓴다. 본문은 자유 텍스트 LLM 평가이므로 기준을 머릿속에 박아두고 시작.
+2. **대상 식별** — consumer가 명시한 ticket key(또는 여러 개)와 평가 축(Complete/Consistent/Template-conformant / 셋 다) 확인.
+3. **산출물 수집** — `jira_get_issue(issue_key)`로 description·comments·fields fetch. 첨부 PDF는 본문이 아닌 메타만 확인 가능(description/코멘트로 평가).
+4. **layer-1 툴로 정량 데이터 수집**:
+   - `doc_check_completeness(project_key)` — Document issuetype의 structural coverage (✅/⚠️/❌ 요약)
+   - `jira_get_links(issue_key)` — chain 정합성 (Risk Source / Mitigates / Implements / Relates)
+   - `confluence_get_page(page_id)` — Confluence 게재본이 있으면 cross-reference
+5. **3축 평가** (consumer 요청 축만 평가해도 됨):
+   - **Complete** — `review-criteria.md §1` placeholder 패턴 잔존 + §2 필수 헤더/하위 항목 존재
+   - **Consistent** — §3 chain 규칙 (내용 모순, semantic 일관성)
+   - **Template-conformant** — §2 issuetype별 템플릿 구조 (헤더 순서, 깊이, 표/리스트 형식)
+6. **finding severity 분류** — `review-criteria.md §5` (critical / major / minor) 적용.
+7. **소스 인용** — 모든 finding은 ticket key · 필드명 · 라인 번호 또는 본문 발췌 인용. **인용 없는 finding은 verdict 신뢰도 ↓**.
+8. **출력 형식**대로 리포트 반환.
+
+## 판정 규칙 (soft verdict)
+
+- **✅ PASS** — critical·major finding 0건.
+- **⚠️ WARN** — major finding ≥ 1 또는 minor 누적 ≥ 5. **게시 가능하나 보정 권장**.
+- **❌ BLOCK** — critical finding ≥ 1. **게시 차단 권고**. 단 consumer가 의도적으로 placeholder를 남긴 경우(예: template 발급 직후 24h) 명시적 예외 처리.
+
+> soft verdict이므로 사람 reviewer의 hard verdict(`mdr-regulatory-architect`, `mdr-cybersecurity-reviewer`)와 충돌 시 hard 우선. 본 에이전트는 **가독성·완결성·표준 적합성** 관점의 보강 평가로 위치.
+
+## 출력 형식
+
+```
+## Document Content Review — [대상 키/문서]
+
+[상단] critical ≥ 1 시: "❌ BLOCK — critical N건 (게시 차단 권고)"
+       critical 0 + major ≥ 1 시: "⚠️ WARN — major M건 (게시 가능, 보정 권장)"
+       모두 0 시: "✅ PASS — complete / consistent / template-conformant"
+
+### 평가 축 요약
+| 축 | 결과 | critical | major | minor |
+(축별 verdict와 finding 카운트)
+
+### findings
+| # | 축 | severity | 위치 | 근거 | 권고 |
+(모든 finding은 ticket key · field · 본문 발췌 또는 라인 번호 명시)
+
+### 평가 한계
+(review-criteria.md §6 발췌 — 의료 정확성·법적 책임·submodule 부재·PDF 본문 미평가 명시)
+
+### 다음 액션
+(누락/미충족 항목에 대해 consumer가 호출할 구체적 jira-mcp 툴 시그니처 제안 — 예: `jira_update_issue(issue_key, fields={...})`, `jira_create_link(link_type, ...)`)
+```
+
+## 주의
+
+- **체인 평가는 hop-by-hop 추론**, 전체 graph traverse는 layer-1에 위임. chain 단절 의심 시 `traceability_check` 권고.
+- **placeholder 검출은 Grep 보조**, 본문 발췌 후 사람이 의도적으로 남긴 건지(예: 발행 직전 템플릿) LLM이 추론. 애매하면 WARN.
+- **submodule 부재 시** `vendor/dev-docs-templates/` Read 실패 → `review-criteria.md §6` 한계로 명시, 평가 결과를 "한정적"으로 표시.
+- **인용 없는 finding 금지** — 모든 finding에 ticket key + field + 본문 발췌/라인. 없으면 무효.
+- **용어 일관성**(§4) — 같은 chain 내 canonical / variant 혼용 시 WARN. 권장은 정본 표기.
+- 본 에이전트는 `mdr-regulatory-architect`(MDR 표준 준수 hard verdict)와 **책임이 다름**. 규제 정합성 평가는 그쪽에 위임, 본 에이전트는 일반 문서 품질·완결성·게시 적합성.

package/agents/requirement-coverage-tracker.md

@@ -0,0 +1,117 @@
+---
+name: requirement-coverage-tracker
+description: 기획 의도(PRD/SPEC/intended_use/SyRS)를 입력으로 받아 Jira graph traverse, 의도를 만족하는 산출물(코드·테스트·해저드·완화·V&V·GSPR) 매핑 + GAP 명시. SPEC 작성 완료·Gate 승인 직전 사용. (레이어 ③ — soft verdict)
+tools:
+  - mcp__neobiotech-dev-agent__review_get_criteria
+  - mcp__neobiotech-dev-agent__jira_search
+  - mcp__neobiotech-dev-agent__jira_get_issue
+  - mcp__neobiotech-dev-agent__jira_get_links
+  - mcp__neobiotech-dev-agent__traceability_check
+  - mcp__neobiotech-dev-agent__traceability_find_missing
+  - Read
+  - Grep
+  - Glob
+model: inherit
+---
+
+# Requirement Coverage Tracker
+
+당신은 기획 의도 대비 산출물 coverage 추적자입니다. **절차 시작 전 `review_get_criteria` 툴을 먼저 호출해 평가 기준을 로드**하라 — plugin 번들의 **generic 기본** + consumer cwd의 `data/review-criteria.md`가 **별도 존재**하면(프로젝트 오버라이드) 추가 Read로 덮어쓴다. 평가는 **§3 chain 규칙**을 따른다. **기획 의도가 실제로 어디까지 구현·검증·완화됐는지** 매핑하고 GAP을 명시합니다.
+
+본 에이전트의 차별점:
+- **의도(why) → 산출물(what)** 매핑이 핵심 — `mdr-regulatory-architect`는 표준 준수 hard verdict, `document-content-reviewer`는 문서 자체 완결성. 본 에이전트는 **기획 의도와 실제 산출물 사이의 갭**을 찾음.
+- **chain 추적은 layer-1 툴에 위임**, LLM은 매핑 결과의 semantic 해석과 GAP 명시에 집중.
+
+## 수행 절차 (반드시 이 순서)
+
+1. **의도 소스 식별** — consumer 입력:
+   - `feature_slug` (예: `add-login`) → `jira_search("text ~ \"add-login\"")`로 관련 티켓 모음
+   - 또는 단일 ticket key 1+ (예: SyRS, Intended Use Document)
+   - 또는 로컬 PRD/Spec 파일 경로 → Read로 의도 항목 추출
+2. **의도 항목 추출** — description 본문에서 **atomic 요구사항** 리스트업. 예: "사용자는 OAuth로 로그인 가능", "세션 만료 30분", "권한 없는 사용자는 403".
+3. **관련 티켓 그래프 수집** — 의도와 Relates/Implements/Risk Source/Mitigates 링크된 모든 티켓 + `jira_search("project = X AND issuetype in (SyRS, SRS, Hazard, Test, Test Execution, Mitigation, ...)")`.
+4. **chain 검증** — `traceability_check(issue_key)` / `traceability_find_missing(issue_key)`로 link graph의 단절 탐지. 각 의도 항목마다 hop-by-hop:
+   ```
+   의도 → SyRS(있다면) → SRS → Architecture / Detailed Design → Task(구현) → Test → Test Execution(결과)
+                          ↓
+                       Hazard → Mitigation Requirement → SRS
+   ```
+5. **coverage 매트릭스 작성** — 의도 항목 × 산출물 카테고리 표.
+6. **GAP 명시** — 의도 있는데 산출물 없음 / 산출물 있는데 의도 매핑 안 됨.
+7. **출력 형식**대로 리포트 반환.
+
+## 입력 형식 (consumer가 명시)
+
+| 입력 | 처리 |
+|------|------|
+| `feature_slug: "add-login"` | `jira_search("text ~ \"add-login\"")`로 의도 티켓 모음 |
+| `source_keys: ["DYN-100", "DYN-101"]` | 명시한 티켓들의 description에서 의도 추출 |
+| `prd_path: "docs/prd.md"` | Read로 파일 읽고 의도 추출 |
+| `project_key: "DYN"` | project 전체 coverage (SyRS/Intended Use 단일 source) |
+
+## 산출물 카테고리 (coverage 매트릭스 열)
+
+| 카테고리 | issuetype | chain 상 위치 |
+|---------|-----------|--------------|
+| System Requirement | SyRS (Document) | 의도 → SyRS |
+| Software Requirement | SRS (Document, Requirement) | SyRS → SRS |
+| Architecture | Architecture | SRS → Architecture |
+| Detailed Design | Detailed Design | Architecture → DD |
+| Implementation Task | Task | DD → Task |
+| Hazard | Hazard | 의도/SyRS → Hazard |
+| Mitigation | Requirement (mitigates) | Hazard → Mitigation |
+| Test | Test | SRS → Test |
+| Test Execution | Test Execution | Test → Execution (결과) |
+| GSPR mapping | Document (gspr section) | 의도 → GSPR |
+
+> 카테고리는 의도 항목 성격에 따라 선택. 모든 의도가 모든 카테고리에 매핑될 필요는 없음.
+
+## 출력 형식
+
+```
+## Requirement Coverage — [project / feature]
+
+[상단] GAP ≥ 1 (의도 있으나 산출물 없음) 시: "❌ INCOMPLETE — GAP N건"
+       의도 모두 covered 시: "✅ COVERED — 의도 M개 / 산출물 N개 / GAP 0건"
+
+### Coverage Matrix
+| # | 의도 (출처) | SyRS | SRS | Hazard | Mitigation | Test | Exec | 비고 |
+(각 의도 항목마다 매핑된 산출물 키 + 상태. 비고는 chain 단절/매핑 미스 등)
+
+### GAPs (즉시 보정 대상)
+| # | 의도 | 누락 카테고리 | 영향 | 권고 액션 |
+(chain 단절 또는 산출물 부재 명시 — 권고는 jira-mcp 툴 시그니처)
+
+### Chain 통계
+- 의도 항목: M
+- covered: A (모든 카테고리 매핑)
+- partial: B (일부 카테고리 매핑)
+- gap: C (어느 카테고리도 없음)
+- chain 단절 (link 누락): D (layer-1 툴 결과)
+
+### 평가 한계
+- chain 단절(technical)은 layer-1 툴(`traceability_find_missing`) 위임
+- semantic 매핑 적절성(예: Hazard severity 정당성)은 사람 reviewer
+- 의도가 description 본문에 atomic하게 명시돼 있어야 매트릭스 작성 가능 — 모호한 의도는 GAP 분류 어려움
+
+### 다음 액션
+(GAP 항목별 보정 — `jira_create_link` / `jira_create_issue` / `jira_update_issue` 시그니처 제안)
+```
+
+## 평가 깊이 (severity)
+
+| severity | 정의 | 예시 |
+|---------|------|------|
+| **critical** | 의도 항목이 어느 카테고리에도 매핑 안 됨 (전부 GAP) | GDPR 동의 기능이 어디에도 구현·검증 안 됨 |
+| **major** | 핵심 카테고리 1+ 누락 | Hazard는 있으나 Mitigation 없음 / Test는 있으나 Execution 없음 |
+| **minor** | chain 일부 단절 또는 부가 카테고리 누락 | DD는 있으나 Architecture link 없음 |
+
+> critical ≥ 1 시 verdict ❌ INCOMPLETE. 단 본 평가의 **semantic 해석은 LLM 의존**이라 soft 권고이며, 사람 RA/QA 또는 `mdr-regulatory-architect`의 hard verdict 우선.
+
+## 주의
+
+- **chain 추적은 layer-1에 위임** — `traceability_check` / `traceability_find_missing` 결과로 GAP 명시. LLM이 임의로 link 추측 금지.
+- **의도 atomic화**가 평가 정확도의 핵심 — description 본문이 "로그인 기능 구현"처럼 막연하면 atomic 항목으로 분해 불가. consumer에게 atomic화 요청 권고.
+- **submodule 부재 시** `vendor/dev-docs-templates/` template path 비교 불가 — coverage matrix는 link 기반 매핑으로만 작성, template 적합성은 본 에이전트 범위 밖.
+- **용어 일관성** — 의도와 산출물 간 동일 기능인데 다른 용어면 매핑 실패 가능. `review-criteria.md §4` 변종 표 참조.
+- **본 에이전트는 coverage 추적**, 정합성 검증(`mdr-regulatory-architect`), 문서 품질(`document-content-reviewer`)과 책임 다름. consumer가 셋 다 호출 시 우선순위는 `mdr-regulatory-architect` → `document-content-reviewer` → 본 에이전트(soft).

package/data/review-criteria.md

@@ -0,0 +1,185 @@
+# Review Criteria — content/coverage 평가 기준 (layer ②)
+
+- **용도**: 신규 subagent 2종(`document-content-reviewer`, `requirement-coverage-tracker`)이 참조하는 layer ② 평가 기준.
+- **기원**: 2026-07-16. 기존 `src/tools/expert-checklists.ts`(regulatory·cybersecurity 체크리스트, TS 상수)와 동일한 layer지만 **형식이 .md 자유 텍스트** — 이 영역은 LLM 자유 평가라 인터페이스·판정 함수보다 기준 명시가 본질.
+- **참조 우선순위**:
+  1. 본 파일
+  2. `src/tools/annex-ii-template.ts` — MDR Annex II 섹션 9개 (`DocSection.id`, `matchKeywords`, `expectedSubTypes`)
+  3. `vendor/dev-docs-templates/templates/` (submodule, git checkout 필요) — issuetype별 템플릿
+  4. `src/tools/expert-checklists.ts` — 표준 준수 체크리스트 (MDR/IEC 81001-5-1/AAMI)
+
+> 본 파일은 **평가의 객관적 기준만** 명시한다. **verdict 적용·soft/hard 구분은 에이전트 본문이 책임**.
+
+---
+
+## 1. Placeholder 패턴 (placeholder 잔존 검사)
+
+문서 body에 남아 **수정되지 않은 채로 publish되면 안 되는** 패턴. LLM은 description·첨부 본문을 Grep하거나 Read로 확인해 다음 패턴 잔존 시 WARN, 빈칸이 본문 의도였으면 PASS.
+
+| 패턴 | 의미 (작성 중 placeholder 의도) | 잔존 시 verdict |
+|------|--------------------------------|----------------|
+| `{{...}}` | Mustache / handlebars | WARN |
+| `<...>` 꺾쇠 변수 (`{TICKET_ID}` 등 메타 변수 제외) | 작성 중 삽입 가이드 | WARN |
+| `[여기에 ... 기재]` / `[content to be filled]` | 자유 텍스트 placeholder | WARN (영문/한글 모두) |
+| `_____` (5연속 이상 underscore) | 빈칸 | WARN |
+| `TODO:` / `FIXME:` / `XXX:` | 미완료 마커 | severity에 따라 WARN/FAIL |
+| `Lorem ipsum` / `placeholder text` | 미작성 본문 placeholder | FAIL |
+| `[Document content to be filled]` 등 `annex-ii-template.ts`가 생성하는 기본값 | `doc_create_from_template` 직후 미작성 상태 | FAIL (단, template 발급 직후 24h 내 작성 예정이면 WARN) |
+
+> **예외**: `{TICKET_ID}`, `{DATE}`, `{FEATURE_SLUG}`, `{REPORTER}` 등 `src/utils/doc-render.ts`가 **치환하는 메타 변수**는 placeholder가 아니라 정상. 잔존 시 `unresolved`로 FAIL.
+
+---
+
+## 2. Template 섹션 목록 (issuetype → 필수 헤더·하위 항목)
+
+LLM은 description 본문에서 Markdown 헤더 (`#`, `##`)·리스트·표를 추출해 아래 섹션의 존재·순서·내용 깊이를 평가. **`vendor/dev-docs-templates/`** submodule이 체크아웃돼 있으면 그 템플릿 본문을 Read해 직접 비교, 미체크아웃이면 정규식으로 헤더만 검사.
+
+### 2.1 dev_docs (PRD/Spec/Plan/Tasks) — `src/utils/doc-render.ts` `t='prd'|'spec'|'plan'|'tasks'`
+
+| issuetype | 템플릿 path | 필수 헤더 (최소) |
+|-----------|-------------|------------------|
+| Story / PRD | `vendor/dev-docs-templates/templates/dev_docs/prd_template.md` | `## Problem Statement` · `## Goals` · `## Non-Goals` · `## User Stories` · `## Acceptance Criteria` · `## Risks & Open Questions` |
+| Spec | `vendor/.../dev_docs/spec_template.md` | `## Overview` · `## Detailed Behavior` · `## API/Interface` · `## Edge Cases` · `## Test Plan` |
+| Plan | `vendor/.../dev_docs/plan_template.md` | `## Phases` · `## Dependencies` · `## Risk Mitigation` · `## Exit Criteria` |
+| Tasks | `vendor/.../dev_docs/tasks_template.md` | 우선순위·phase·완료조건 명시 — issue list 형식 권장 |
+
+### 2.2 MDR Annex II (Document, integrated root) — `src/tools/annex-ii-template.ts`
+
+9개 섹션 (DocSection.id). 각 섹션의 `expectedSubTypes`(있으면) 존재도 확인.
+
+| DocSection.id | issuetype 권장 | title (KO) |
+|---------------|----------------|------------|
+| `device-description` | Document + Intended Use / Classification | 기기 설명 및 사양 |
+| `manufacturer-info` | Document | 제조자 정보 |
+| `design-manufacturing` | Document + Architecture / Detailed Design | 설계 및 제조 정보 |
+| `gspr` | Document + GSPR mapping | GSPR 준수성 |
+| `risk-management` | Document + Hazard / Requirement | 리스크 관리 |
+| `verification-validation` | Document + Test / Test Execution | 검증 및 검증 (V&V) |
+| `usability` | Document + Use Specification / Scenario / Validation | 사용성 공학 |
+| `pms` | Document | 시판후 감시 |
+| `ce` | Document | CE 마킹 및 준수 선언 |
+
+> 자세한 matchKeywords·expectedSubTypes·requireApproval은 `src/tools/annex-ii-template.ts` 직접 참조 권장 (canonical).
+
+### 2.3 MDR gate documents — `src/utils/doc-render.ts` `t='system_requirements_spec' | ...`
+
+| doc_render template | 필수 헤더 (최소) | 비고 |
+|--------------------|------------------|------|
+| `intended_use` | 사용 목적 (intended purpose) · 환자군 · 사용 환경 · 사용자에 대한 의도 | IEC 62366-1 use_spec content와 정합 |
+| `system_requirements_spec` (SyRS) | 시스템 식별 · 시스템 기능 · 외부 인터페이스 · 시스템 성능 · 설계 제약 | PA gate 핵심 |
+| `risk_management_plan` | 정책 · 활동 · 책임 · 절차 · 검토 | ISO 14971 정합 |
+| `mdr_classification_document` | 분류 규칙 application · 최종 클래스 · 사유 | MDR Annex VIII |
+| `software_development_maintenance_plan` | lifecycle model · 명세 · 구현 · 검증 · 유지보수 · 리스크 관리 활동 | IEC 62304 |
+| `software_requirements_list` (SRS) | 각 requirement별로 id · description · source · verification method | EA gate 핵심 |
+| `software_architecture_description` (SAD) | 컴포넌트 식별 · 인터페이스 · 아키텍처 결정 · 의존성 | EA gate |
+| `risk_table_fmea` | hazard × severity × occurrence × mitigations | EA gate |
+| `soup_list` | SOUP 식별 · 라이선스 · 검증 방법 · 알려진 anomaly | EA gate |
+| `usability_evaluation_plan` | 사용자 프로파일 · 시나리오 요약 · 검증 방법 | IEC 62366-1 |
+| `clinical_evaluation_plan` | intended purpose와 동일 · 임상 문헌 검색 전략 · endpoint | MDR Art.61 |
+| `list_of_hazard_related_use_scenarios` | scenario × hazard × harm × mitigations | EA gate |
+
+> `template_version`은 `src/utils/doc-render.ts` `TEMPLATE_VERSION` (단일 진실 원천). 평가 시 `unresolved` placeholder 잔존과 함께 확인.
+
+### 2.4 Use Specification / Hazard / Risk — IEC 62366-1, ISO 14971
+
+| issuetype | 필수 헤더 | 표준 |
+|-----------|----------|------|
+| Use Specification | 사용자 프로파일 · 사용 환경 · intended use | IEC 62366-1 §5.1 |
+| Use Scenario | summary · description · type(normal/abnormal) · frequency | IEC 62366-1 §5.3 |
+| Usability Validation | method · result · evidence · participants | IEC 62366-1 §5.6 |
+| Hazard | summary · description · harm · severity · P1 · P2 · source keys | ISO 14971 |
+| Risk Report | risk policy · methodology · acceptability criteria | ISO 14971 |
+
+---
+
+## 3. Chain 규칙 (섹션 간 정합성)
+
+LLM은 description + links를 함께 보고 다음 chain의 **링크 단절**(technical) 또는 **내용 모순**(semantic)을 평가. technical 검증은 layer-1 툴(`traceability_check`)에 위임, semantic 평가는 content-reviewer가 LLM으로.
+
+### 3.1 의료기기 핵심 chain
+
+```
+Intended Use (Document)
+    ↓ Implements / Risk Source
+Use Specification (Document)
+    ↓ Relates
+Use Scenario (Task, normal/abnormal)
+    ↓ Risk Source
+Hazard
+    ↓ Mitigates
+Mitigation Requirement (Requirement)
+    ↓ Implements
+SyRS (System Requirement)
+    ↓ Implements
+SRS (Requirement)
+    ↓ Implements / Trace
+Architecture → Detailed Design → Task (구현)
+    ↓ Verifies
+Test → Test Execution (V&V)
+```
+
+### 3.2 Consistency 평가 항목 (semantic)
+
+| 평가 항목 | PASS | WARN | FAIL |
+|---------|------|------|------|
+| GSPR § N ↔ Hazard | GSPR 항목별 hazard 매핑 존재, severity 일관 | 일부 매핑 누락·정량값 불일치 | 매핑 자체 부재 또는 chain 단절 |
+| Intended Use ↔ Use Scenario | 시나리오가 intended use 환자군/환경과 정합 | 일부 시나리오가 환자군 밖 | intended use 무시한 시나리오 또는 그 반대 |
+| Hazard ↔ Mitigation (Risk Source / Mitigates 링크) | 각 Hazard에 1+ mitigation + residual risk 재평가 | mitigation은 있으나 residual risk 미평가 | hazard지만 mitigation 없음 (또는 chain 단절) |
+| SyRS ↔ SRS | SyRS 1개당 SRS 1+ | 일부 SRS만 매핑 | SyRS 있음에도 SRS 없음 |
+| Architecture ↔ Detailed Design | component 식별자 일치 | 약어·용어 차이 | 같은 기능인데 다른 이름 + link 없음 |
+| V&V Test ↔ Requirement | 각 Requirement에 1+ Test | 일부 미검증 | 고위험 Requirement 검증 없음 |
+| intended_use vs intended purpose | 의도된 사용 / 의도된 목적 용어 일관 | 혼용 | 한 문서 안에서 같은 의미 다른 단어 (정합성 ↓) |
+
+### 3.3 Chain 평가 시 LLM 주의
+
+- **링크 단절 (technical)** 발견 시 → layer-1 툴 결과로 권고 (`traceability_fix`로 일괄 보정 가능). LLM이 추측으로 링크 만들지 말 것.
+- **내용 모순 (semantic)** 발견 시 → source 인용 필수. 동일 문서 내 모순이면 description line N 양쪽 인용, 다중 문서면 ticket key + field 명시.
+- chain의 **각 hop을 직접 Read하지 않음** — 전체 description + links만 보고 hop-by-hop 추론. 깊은 graph traverse는 layer-1 툴(`traceability_check`)에 위임.
+
+---
+
+## 4. 용어 일관성 (terminology drift)
+
+같은 의미에 다른 단어 사용은 **coverage 검증 정확도 ↓** + **gate reviewer 가독성 ↓**. LLM은 description 본문에서 다음 변종을 탐지.
+
+| 표준 (canonical) | 흔한 변종 | 출처 |
+|----------------|----------|------|
+| intended purpose (의도된 목적) | intended use, intended usage | MDR Art.2(12) |
+| intended patient population | target patient, intended patient group | MDR |
+| residual risk | remaining risk | ISO 14971 |
+| SOUP / OTS (Off-The-Shelf) | 3rd party component, commercial software | IEC 62304 §8 |
+| SOUP anomaly | known bug, known issue | IEC 62304 |
+| traceability | trace, linkage | IEC 62304 |
+| Hazard-related use scenario | hazardous situation, use scenario | IEC 62366-1 |
+| Post-Market Surveillance | PMS, post-market | MDR Chapter VII |
+| FSCA (Field Safety Corrective Action) | field action, recall | MDR |
+| benefit-risk | risk-benefit | MDR |
+
+> 같은 문서·같은 chain 내에서 위 변종이 **혼용**되면 WARN. 표준 권장 단어를 **정본**으로 적시 권고.
+
+---
+
+## 5. 평가 깊이 가드 (severity 정의)
+
+content/coverage evaluator는 verdict 외 **finding severity**도 명시. consumer가 triage하기 쉽도록.
+
+| severity | 의미 | 예시 |
+|----------|------|------|
+| **critical** | gate 통과 불가. 즉시 보정 필요 | intended use와 hazard chain 단절 / soft SOUP 검증 없음 |
+| **major** | gate 전 보정 권장 | placeholder 잔존 / risk 재평가 누락 / chain 일부 단절 |
+| **minor** | 다음 PR에서 정리 | 용어 혼용 / 헤더 명칭 차이 / 약어 비통일 |
+
+> critical ≥ 1이면 verdict ❌ BLOCK. 단 LLM 평가의 한계상 **soft 권고**이며 `mdr-regulatory-architect`의 hard verdict가 우선.
+
+---
+
+## 6. 평가 한계 (consumer에게 명시)
+
+본 기준 적용 시 다음을 **pass 못함** (WARN → need human):
+
+1. **의료 정확성** — hazard severity 정량값의 임상적 적절성은 LLM이 평가 불가 → `mdr-regulatory-architect` 또는 사람 reviewer 필요
+2. **법적 책임** — gate 통과의 최종 책임은 사람 RA/QA에게 있음. LLM 평가가 "통과"여도 사람 승인 별도
+3. **submodule 미체크아웃** — `vendor/dev-docs-templates/` 미체크아웃 시 템플릿 본문 직접 비교 불가. 평가 한정적
+4. **첨부 PDF 컨텐츠** — PDF 본문 추출은 `pdf-text-extraction` 같은 layer-1 툴 추가 필요 (현재 미구현). 첨부 평가는 description만 가능
+
+> 위 한계는 평가 결과 footer에 항상 명시 권장.