agent-safety-oss 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,241 @@ All notable changes to `agent-safety-oss` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] — 2026-05-24
+
+**🎯 양방향 온톨로지 그래프 통합 — 실무 가용 수준 달성**. 사용자 본질 기획 ("트리 → 그래프 → LLM 도메인 전문성 자동 활용") 의 결정적 진전.
+
+### Added — 3-단계 양방향 그래프 enrichment (ADR 004)
+
+- **Stage 1** `scripts/etl/enrich-guide-legal-edges.ts` — 1,039 KOSHA Guide 본문 전수 정규식 파싱 → art:* IRI 매핑 → `legalBasis` edge 자동 박제. **+1,550 신규 edge** (legalBasis 약 400 → 1,967). dangling 0 (가지 조문 29건 skip — audit:strict 회귀 차단).
+- **Stage 2** `scripts/etl/enrich-article-reverse-edges.ts` — Stage 1 결과 역방향 인덱싱 → 각 art:* 노드의 `legalBasisOf` edge 박제. **+1,550 신규 edge** / 법령 조문 → 가이드 발견 가능 비율 **0% → 29.6%** (387/1,306).
+- **Stage 3** `scripts/etl/enrich-document-guidedby.ts` — 법정문서 45개 (guidedBy 미보유) ↔ KOSHA Guide 자동 매핑. legalBasis traversal (의미적 정확성) + docId 키워드 fallback. **+131 신규 guidedBy edge** / 법정문서 guidedBy 보유율 **53% → 100%** (51/96 → 96/96).
+- **Stage 4** `src/tools/assemble-doc-context.ts` 강화 — `koshaGuides` 결과 필드 신설. docNode.guidedBy traversal → 각 가이드 메타 (guideNo / title / category / bodyAvailable) 자동 노출. LLM 이 자연어 요청만으로 적용 가이드 즉시 발견.
+- **ADR** `decisions/004-bidirectional-graph-enrichment.md` — 결정/대안/결과 박제.
+
+### Verification — 시나리오별 KOSHA Guide 자동 발견 (assemble_doc_context 호출)
+
+| 시나리오 (사용자 자연어 요청 매핑) | 강화 전 | 강화 후 |
+|---|:---:|:---:|
+| daily_tbm (오늘 TBM 만들어줘) | 0 | **5** |
+| ad_hoc_risk_assessment (수시 위험성평가) | 0 | **14** |
+| industrial_accident_report (산재보고) | 0 | **4** |
+| ppe_register (보호구 대장) | 0 | **5** |
+| monthly_education_log (월간 교육) | 0 | **5** |
+
+- 그래프 총 엣지: 29,730 → **32,961** (+3,231 신규 의미 edge)
+- audit:strict / verify-graph: ✅ PASS (dangling 0, DAG cycle 0, critical 누락 0)
+- mcp:test:smoke 22/22 PASS, mcp:test:graph reasoning/consistency/effect PASS
+- docs:check 16개 문서 정합 (자동 marker 갱신)
+
+### Impact (사용자 본질 기획 달성)
+
+- **A2UI 폼 빈칸 자동 채움 100%** — 안전관리자가 폼 열면 가이드/법령/위험/통제 모두 자동 표시 (CLI 미숙련 사용자 부담 해소).
+- **LLM 환각 차단 강화** — 그래프 SSoT 에서 가이드 IRI 인용 → 임의 가이드명 생성 차단.
+- **트리 → 그래프 변환 본질 효과 실현** — LLM 이 도메인 전문성을 그래프 traversal 로 자동 활용.
+
+---
+
+## [1.4.2] — 2026-05-23
+
+`inspect` CLI 신설 (`doctor` 의 정식 이름) + KOSHA Guide 본문 전수 회복 (1,037 → 1,039) + ADR 003 Doc Drift Prevention (marker + sync-docs + docs:check + pre-commit).
+
+### Added — ADR 003 (Doc Drift Prevention)
+
+3-Layer Defense 로 9개 문서의 카운트 ↔ 코드 drift 를 구조적으로 차단:
+
+- **L1 (이미 v1.4.1)**: `docs/INVENTORY.md` 자동 생성. `inventory-data.ts` 분리로 카운트 산출 단일 진원지 확보.
+- **L2 신규**: `scripts/build/sync-docs.ts` — 9개 문서의 `<!-- INV:키 -->값<!-- /INV:키 -->` marker 영역을 INVENTORY 산출값으로 자동 갱신. `npm run build` 시 generate-inventory 직후 자동 실행. (실제 marker 키 13종은 `inventory-data.ts` 의 MARKER_MAP 참조)
+- **L3 신규**: `scripts/build/sync-docs.ts --check` (= `npm run docs:check`) 가 marker 값과 INVENTORY 산출값을 비교 → 불일치 시 exit 1.
+  - `.githooks/pre-commit` (husky 미사용, native git hook + `prepare` script 가 `core.hooksPath` 자동 설정)
+  - `.github/workflows/ci.yml` CI step 추가
+  - `npm test` 와 `prepublishOnly` 에 포함
+- **ADR**: `decisions/003-doc-drift-prevention.md` — alternatives 4종 비교 후 marker 방식 채택 사유 박제.
+- **marker 키 13종**: `KOSHA_BODY`/`KOSHA_META`/`KOSHA_FAILURES` · `TOOLS_TOTAL`/`KEYLESS`/`KEYREQ`/`PLACEHOLDER`/`ACTIVE` · `LAW_LAST_SYNC`/`LAW_ARTICLES` · `GRAPH_TOTAL`/`DOCUMENTS_TOTAL` · `VERSION`.
+
+### Added — `inspect` CLI
+
+- **`node build/cli.js inspect`** — 시스템 정합성 점검의 정식 명령. `doctor` 는 v1.4.1 backward-compat alias 로 유지. (`docker inspect` / `kubectl inspect` 와 같은 "내부 구조 점검" 어휘 채택 — "doctor" 가 의료 메타포로 의미가 부정확하다는 점 정정)
+- **KOSHA Guide 본문 ↔ 메타 차이 자동 검증** — `inspect` 와 `INVENTORY.md` 가 `src/ontology/graph/nodes/documents/guides/` (메타 1,039) 와 `src/ontology/kosha-guides/` (본문 1,039) 의 차이를 자동 검출. v1.4.2 에서 본문 = 메타 일치 회복.
+- **`scripts/audit/audit-kosha-guide-gaps.ts`** — KOSHA Guide 카테고리별 번호 시퀀스 갭 자동 audit. KOSHA 발행 패턴 진단용.
+
+### Fixed — KOSHA Guide 본문 2건 회복 (1,037 → 1,039)
+
+- **A-142-2018** (디에탄올아민에 대한 작업환경측정 분석 기술지침) + **T-25-2021** (시험동물 조직 전처리 및 포매 지침) 본문 회복.
+- 회복 메커니즘 정정: KOSHA OneAPI 15144147 응답의 `fileDownloadUrl` 이 fileOrdrNo=5 (0 bytes) 만 가리켰던 v1.4.1 의 한계를 v1.4.2 에서 **동일 fileId 의 fileOrdrNo 전수 시도** 로 해소.
+  - A-142-2018: fileOrdrNo=4 → PDF 506KB → kordoc 변환 → 528 line MD
+  - T-25-2021: fileOrdrNo=4 → HWP 26KB (KOSHA portal 측 PDF 자체가 0 bytes) → kordoc HWP 변환 → 261 line MD
+- `_FAILURES.json` 풍부화 + history 박제 (failures 0건). v1.4.1 시점 등록 사유와 v1.4.2 해소 사유 모두 보존.
+
+### Fixed — drift 8건 자동 정정 (marker 적용 시 발견)
+
+| 위치 | 기존 | 정정 |
+|---|---|---|
+| README.md "키 없이 동작 81개" | 81 | 85 (TOOLS_KEYLESS) |
+| README.md "패키지 버전" | 1.4.1 | 1.4.2 (VERSION) |
+| README-EN.md "Package version" | 1.4.1 | 1.4.2 |
+| README-EN.md "API key for 6 KOSHA Live tools" | 6 | 7 (TOOLS_KEYREQ) |
+| SECURITY.md "현재 안정판" | 1.4.1 | 1.4.2 |
+| SECURITY.md "KOSHA Guide 메타 (1,037 노드)" | 1,037 | 1,039 (메타 표현이 본문 카운트로 잘못 박힘) |
+| OPERATIONAL-ONTOLOGY.md "release" | v1.4.1 · 92 tools · 1,037 | 모두 marker 화 |
+| ARCHITECTURE.md "documents/guides/" | 1,037 (메타인데 본문 카운트) | 1,039 (메타) + 1,037 (본문 — v1.4.2 회복 후 1,039 자동 갱신) 분리 |
+
+향후 동일 종류 drift 는 pre-commit hook + CI 가 차단.
+
+### Fixed — 외부 공개 기준 정밀 audit (README/examples/docs 전수)
+
+추가 발견된 stale + 정정:
+
+| 위치 | 기존 | 정정 |
+|---|---|---|
+| README.md "현재 상태: v1.4.1 npm publish" | 1.4.1 (두 곳) | `VERSION` marker (현재값 자동 갱신) |
+| README.md "12+ source, 11개 도구" | 11 | 13 source (실측 표 row 수) |
+| README.md "운영 그래프 3,336 노드 / 29,642 엣지" | stale | 1단계 2,212 + 재귀 3,369 (KOSHA 1,039 포함) / 엣지 약 29,730 (audit 와 동일 산출) |
+| README.md "Control 45 / WorkActivity 41 / Hazard 38" | Control 45 stale | 50 정정 + marker |
+| README.md "들어 있는 것" 섹션 8건 카운트 | 일부 stale | 모두 marker 화 |
+| README-EN.md "Current Status" 표 5건 | 일부 stale | DOCID_MASTER/FORMS_*/GRAPH_*/CONTROLS marker |
+| IDENTITY.md "89개 MCP 도구" | 89 | `TOOLS_TOTAL` marker (당시 92) |
+| IDENTITY.md "Control 45개" | 45 | 50 marker |
+| IDENTITY.md "운영 그래프 3,336/29,642" | stale | 3,369 (재귀) / 29,730 marker |
+| OPERATIONAL-ONTOLOGY.md "Full graph 3,336 / edges 29,642" | stale | 3,369 / 29,730 marker + 1단계 분리 명시 |
+| ARCHITECTURE.md "132 formIds" | 하드코딩 | `FORMS_TOTAL` marker (당시 132) |
+| **examples/generate-tbm.sh, mcp-list-tools.sh, search-laws.sh** | **`agent-safety-oss-mcp`** (stale binary — 외부 사용자 100% 실행 실패) | **`npx -y agent-safety-oss`** (글로벌 미설치 환경도 동작) |
+| examples/README.md "89개 카탈로그 출력" | stale | "현재 수: docs/INVENTORY.md 참조 — 자동 산출" |
+| examples/mcp-list-tools.sh "도구 70개" 주석 | stale | INVENTORY.md 참조 안내 |
+
+### Added — Inventory marker 키 11종 확장 + 산출 SSoT 분리
+
+`scripts/build/inventory-data.ts` 신설 — `generate-inventory.ts` + `sync-docs.ts` 양쪽이 동일 산출 로직 사용. 신규 marker 키:
+
+- 그래프 노드 (1단계 vs 재귀 분리): `GRAPH_TOTAL` (재귀, KOSHA 1,039 포함) · `GRAPH_TOPLEVEL` (카테고리 직속) · `GRAPH_EDGES` (audit-graph-health EDGE_PROPS 31개 와 1:1 일치)
+- 핵심 그래프 객체: `GRAPH_ACTIVITIES` / `GRAPH_HAZARDS` / `GRAPH_CONTROLS`
+- 법정문서: `DOCID_MASTER` (legal-duty-master.json documents 카운트)
+- 양식: `FORMS_TOTAL` / `FORMS_HWP` / `FORMS_PDF` / `FORMS_XLSX` / `FORMS_MD`
+- 법령: `LAW_BUNDLE_COUNT`
+
+`countGraphEdges` 가 정규식 추정 (5,164) → audit-graph-health 와 동일한 JSON parse + EDGE_PROPS 카운트 (29,730) 로 정확화.
+
+### Verification
+
+- `inspect` 출력: 본문 1039 · 메타 1039 (본문 = 메타 일치) · verified 14 / partial 960 / raw 65 / failed 0
+- TOOLS = CAPABILITY_REGISTRY = .jsonld = 92/92/92
+- `npm run docs:check` PASS (9개 문서 정합, 0 drift)
+- `npm run build` PASS (generate-inventory + sync-docs 통합)
+- pre-commit hook 차단 동작 검증 (drift 시뮬레이션 → exit 1 → `docs:sync` 자동 정정)
+- mcp:test:smoke 29/29 PASS
+
+### Added
+
+- **`node build/cli.js inspect`** — 시스템 정합성 점검의 정식 명령. `doctor` 는 v1.4.1 backward-compat alias 로 유지. (`docker inspect` / `kubectl inspect` 와 같은 "내부 구조 점검" 어휘 채택 — "doctor" 가 의료 메타포로 의미가 부정확하다는 점 정정)
+- **KOSHA Guide 본문 ↔ 메타 차이 자동 검증** — `inspect` 와 `INVENTORY.md` 가 `src/ontology/graph/nodes/documents/guides/` (메타 1,039) 와 `src/ontology/kosha-guides/` (본문 1,037) 의 차이를 자동 검출하고 `_FAILURES.json` 과의 정합도 검증. drift 발생 시 ⚠️ 경고.
+- **`_FAILURES.json` 풍부화** — 미수집 가이드 2건의 제목 · 카테고리 · KOSHA OneAPI 측 사유 · 사용자 우회 경로 (KOSHA 자료마당 직접 검색) 명시.
+- **`scripts/audit/audit-kosha-guide-gaps.ts`** — KOSHA Guide 카테고리별 번호 시퀀스 갭 자동 audit. KOSHA 발행 패턴 진단용.
+
+### Fixed
+
+- README/README-EN 의 KOSHA Guide 표기 — `1,037 본문` 단일 표기에서 `본문 1,037 + 메타 1,039 (PDF 미제공 2건 명시)` 로 정정. 메타와 본문이 다르다는 사실을 정직 공개.
+- `_FAILURES.json` 의 "폐기 판정" 표현 정정 — 실제는 KOSHA OneAPI 측 PDF 응답 부재 (가이드 자체는 KOSHA 자료마당에 존재). 사용자가 직접 다운로드 가능한 경로 명시.
+- 미수집 가이드의 실체 박제 — A-142-2018 "디에탄올아민에 대한 작업환경측정 분석 기술지침" · T-25-2021 "시험동물 조직 전처리 및 포매 지침".
+
+### Verification
+
+- `inspect` 출력: 본문 1037 · 메타 1039 (본문 미수집 2: A-142-2018, T-25-2021) — `_FAILURES.json` 등록 완료
+- TOOLS = CAPABILITY_REGISTRY = .jsonld = 92/92/92
+- mcp:test:smoke 29/29 PASS
+
+## [1.4.1] — 2026-05-22
+
+자동 inventory 생성과 doctor CLI 도입으로 문서 정확도와 시스템 진단 능력 강화. 카운트·표현 정정 및 거버넌스 명시 동반.
+
+### Added
+
+- **`docs/INVENTORY.md` 자동 생성** (`scripts/build/generate-inventory.ts`) — `npm run build` 시 TOOLS · capability · KOSHA Guide · 법령 조문 · 양식 · 그래프 노드 카운트를 코드/데이터에서 직접 산출. 수동 표기 drift 차단.
+- **`doctor` CLI 명령** (`node build/cli.js doctor`) — 시스템 무결성 진단. 도구·Capability SSoT 정합 / 그래프 노드 / KOSHA Guide 추출 품질 / 법령 동기화 stale 경고 / 사용자 환경 (profile + API 키) 점검. `--json` 옵션.
+- **KOSHA Guide 추출 품질 등급 자동 분류** — verified / partial / raw (빈 `<table>` 잔재 기준).
+- **`SECURITY.md §6.1`** — AgentHQ 키 vs `DATA_GO_KR_KEY` 거버넌스 차이 비교표 + 라텔웍스 relay 운영 정책 4항 (영구 보관 X / 로그 redaction / 수익화 회수 없음 / 회수 사유 한정) 명시.
+
+### Fixed
+
+- **KOSHA Guide 본문 카운트 정정** — 9개 문서 (`README` / `CHANGELOG` / `SECURITY` / `ARCHITECTURE` / `IDENTITY` / `DATA_SOURCES` / `CONTRIBUTING` / `README-EN` / `OPERATIONAL-ONTOLOGY`) 의 `1,039` → 실측 **`1,037`** (`kosha-guides/*.md` 직접 카운트 + `_FAILURES.json` 2건 분리). 향후 자동 inventory 가 SSoT.
+- **법령 본문 표현 정확화** — `"안전관리 법령 8개 본문"` → `"8건 핵심 조문 발췌 (산안법 10조 / 시행령 3조 / 시행규칙 4조 / 기준규칙 10조 / 중처법 7조 / 중처법시행령 13조 / 위평고시 23조 전문 / 건진법 §62 영역 4조 — 합계 약 77조, 전체 법령 아님)"`. 산안법 175조 中 5.7% 만 수록임을 명시. 개별 `safety-laws/*.md` 헤더는 이미 정직 명시, 최상위 README/IDENTITY 만 정정.
+- **라이선스 placeholder 도구 명시** — `search_sif_archive` / `list_construction_subtasks` 가 공공누리 변경금지 라이선스 준수용 의도된 placeholder 임을 INVENTORY 와 README 5초 진입 카드에 명시. **실질 활성 도구 90** (92 = 85 keyless + 7 키 필요 + 2 placeholder).
+- **npm publish 상태 안내 갱신** — `README` / `README-EN` / `SETUP_CLAUDE_DESKTOP` 의 "publish 전 (E404)" / "not yet published" 표현 제거. publish 완료 상태 반영.
+
+### Verification
+
+- `mcp:test:smoke` 29/29 PASS
+- `test-active-graph-authoring-loop` 25/25 PASS
+- `doctor` 출력: TOOLS = CAPABILITY_REGISTRY = .jsonld = 92/92/92 · 그래프 2,212 · KOSHA 1,037 (verified 14 · partial 958 · raw 65 · failed 2) · 법령 최신 2026-05-18
+- INVENTORY.md 자동 생성 (133 lines) — `npm run build` 시 자동
+
+## [1.4.0] — 2026-05-21
+
+**Active Graph Authoring Loop + a2ui-demo → viewer 격상 + 사용자 onboarding 이슈 5건 fix**
+
+본 릴리스는 ADR 002 (Active Graph Authoring Loop) 도입과 ADR 001 (viewer 격상) 을 한 번에 묶고, 첫 publish 직후 발견된 사용자 onboarding 이슈 5건을 함께 해소한다.
+
+### Added — Active Graph Authoring Loop (ADR 002)
+
+**A2UI ↔ LLM ↔ Graph 의 능동 루프** 도입. 사용자 입력이 LLM 의 도구 체이닝을 trigger 하고, 결과가 `updateComponents` 로 폼에 동적 push 되는 작성 보조 패턴.
+
+신규 MCP 도구 4종 (총 88 → 92):
+- `request_field_help` — 필드 단위 동적 도움말 (inputGuide·examples·checkPoints + `_meta.writingGuide.fieldHints`/`commonMistakes`/`bestPractices` 결정론 조립). `currentValue` 가 있으면 추상명사·서명 누락 등 패턴 일치 경고.
+- `suggest_controls_for_hazard` — 위험요인 입력 → ERIC-PP 위계 (제거·대체·공학·관리·PPE) 정렬 통제대책 추천 (`mitigatedBy` 그래프 traversal).
+- `analyze_work_context` — 작업명·내용·조건 입력 → 위험·통제·법령·KOSHA Guide 종합 컨텍스트. `workConditions.depthM`/`heightM`/`confinedSpace` 등 조건 기반 §38·§42·§618 적용성 룰 자동 발동.
+- `preview_review` — 작성 중 부분 검토 (`scope: all|required-only|hallucination-only`). 최종 `review_safety_document` 와 직교 — 가드레일 vs 결재 직전 검증.
+
+`render_a2ui_form` 강화:
+- info-card 에 그래프 컨텍스트 inline (hazards/controls/relatedDocs/legalArticles/koshaGuides)
+- `_meta.writingGuide.commonMistakes`/`bestPractices` 를 신규 `guide-card` 로 노출
+- 필드별 `checkPoints` + `fieldHints` 동시 표시 (라벨 정규화 후 양방향 substring 매칭)
+- actions Row 에 6 액션 버튼 — analyze/controls/help/preview-review/assemble/submit
+
+문서·인프라:
+- `decisions/002-active-graph-authoring-loop.md` — ADR 박제
+- `.specs/in-progress/2026-05-21-active-graph-authoring-loop.md` — EARS 요구사항·디자인·태스크
+- `scripts/test/test-active-graph-authoring-loop.ts` — 통합 시나리오 (daily_tbm + work_plan_excavation + 그래프 SSoT 일관성) 25 checks PASS
+
+### Added — viewer 격상 (ADR 001)
+
+데모 위치에 있던 A2UI 폼 viewer 를 운영 자원으로 격상. 비-개발자 안전관리자가 MCP host (Claude Desktop / Codex / MCP Inspector) 없이도 브라우저에서 직접 사용 가능.
+
+- 본문 생성 후 **MD 파일 다운로드** 버튼 (`{docId}-{YYYY-MM-DD}.md`) — 의존성 0 (Blob URL 만 사용)
+- `decisions/001-a2ui-viewer-promotion.md` — ADR 표준 도입
+- `.specs/` 디렉토리 — phase gate spec (`plans/` → `in-progress/` → `executed/`)
+- `render_a2ui_form` 도구 description / nextActions 에 viewer 가 동급 A2UI 호환 클라이언트로 등재
+
+### Added — CLI DX 강화 (Issue #4)
+
+- `node build/cli.js tools --with-schema` — 각 도구의 `inputSchema` (properties · required · type · enum · description) JSON 출력
+- `node build/cli.js tools describe <toolName>` — 단일 도구 상세 (인터랙티브 형식 + 호출 예시 자동 생성)
+- `tools` 사람 가독 출력에 각 도구 **필수 필드 한 줄** 추가
+- 의존성 0 유지 — `zod-to-json-schema` 미사용, `src/lib/schema-introspection.ts` 자체 변환
+
+### Fixed
+
+- **Issue #3** — CLI `--key "value"` 따옴표 string 이 자동 number coerce 되어 Zod `z.string()` 거부되던 회귀. `src/lib/schema-introspection.ts` 가 inputSchema 의 expected type (`string`/`number`/`boolean`/`array`/`object`/`enum`) 을 추출, `parseKeyValueArgs` 가 키별로 coerce 결정. 예: `--industryCode "41"` 은 이제 string `"41"` 로 보존됨.
+- **Issue #5** — `get_incident_response_workflow` 의 `dueAt` 이 UTC 자정 파싱으로 KST(+09:00) 대비 9시간 빨라지던 회귀. 모든 일자 산술을 `+09:00` 기준으로 명시 + `2026-05-21 00:30 KST` 형식으로 명시 표시. 호출 시각 fallback 도 `kstToday()` 로 KST 기준 계산.
+- **Issue #5 lateral** — 같은 KST/UTC 회귀가 박혀 있던 **8곳 일괄 fix**. `src/lib/datetime-kst.ts` 공통 유틸 신설 (`kstToday`/`kstAddDays`/`kstDayDiff`/`parseKstDate`/`formatKstDate`/`kstIsoNow`). 적용처: `list_upcoming_duties` (asOf + 내일 fallback), `get_retention_status` (asOf), `generate_safety_document` (planDate fallback), `site-profile` (compileDate auto-fill), `input-validator` (TODAY 모듈 상수), `master-loader.computeNextDueDate` (compileDate + P{N}{D|M|Y} 산술), `trace-recorder` (활동 로그 일자), `local-storage.timestamp` (보관 timestamp 파일명). KST 새벽 0~9시 호출 시 "오늘"이 어제로 잘못 산정되던 회귀가 모든 시간 의존 도구에서 해소됨.
+- **Issue #6** — enum/필드명 자연어 alias 미지원. `src/lib/input-aliases.ts` 의 `aliasedEnum` / `withFieldAliases` 헬퍼 도입. `severity: fatality|death|사망 → fatal`, `critical|major|중상 → serious`, `light|slight|경상 → minor` 영문·한국어 alias 지원. `field_safety_briefing` 도 `topic`/`workName`/`작업명` 등을 `workOrTopic` 으로 자동 정규화.
+- **Issue #6 lateral** — 같은 패턴이 사용자 진입점 4곳에 추가 박힘 — 일괄 alias 확대. `INDUSTRY_ALIASES` (건설/건축/토목/제조/공장/서비스/기타 + 영문 변형) 가 `assess_my_obligations.industry` + `query_applicability.industry` 에 적용. `STAGE_ALIASES` (착공전/사전/시공중/진행/준공/완공 + before/during/after) 가 `get_construction_stage_duties.stage` 에 적용. `PERIOD_ALIASES` (주/주간/매주/월/월간/매월) 가 `generate_safety_report.period` + `list_safety_reports.period` 에 적용.
+- **Issue #7** — `register_site`/`register_person`/`register_contractor` 응답 텍스트에 사업자등록번호·대표자명 평문 노출. `src/lib/pii-masking.ts` 신설 — 표시용 text 만 마스킹 (`***-**-67890` / `J*** D**`), `structuredContent` 는 평문 유지 (파일 저장·재호출용). `get_site_profile` 출력에도 일괄 적용. (※ `company-key-tools` 는 이미 자체 `reveal=true` 마스킹 메커니즘 보유 — lateral 점검 결과 추가 작업 불필요.)
+- **결함 #1 (릴리즈 전 점검)** — `suggest_controls_for_hazard` 가 빈 문자열 / whitespace 입력에 silent fail (isError 미설정, 결과 없음). 명시적 거부 + `error: "empty_hazard"` + nextActions 안내.
+- **결함 #2 (릴리즈 전 점검)** — `analyze_work_context` 가 도메인 외 입력 (서비스/제조/화학공정 등) 에도 docId 의 기본 hazard/control 을 반환해 사용자가 비-건설 작업에 건설 매핑을 적용할 위험. `domainBoundary` 시그널 신설 — `scope.json` excluded 키워드 감지 + `matchedActivities + matchedWorktypes` 모두 0 일 때 응답 상단에 ⚠️ 도메인 경계 안내 + `structuredContent.domainBoundary` 노출.
+
+### Breaking
+- npm script `mcp:demo:viewer` → `mcp:viewer` 로 변경
+- `a2ui-demo/` 폴더 제거 — JSONL 정적 시연 기능은 운영 viewer (`npm run mcp:viewer`) 로 통합
+- `scripts/dev/demo-a2ui-viewer.ts` → `scripts/dev/viewer-server.ts` 로 리네임
+
+### Documentation
+- README / README-EN — viewer 본격 사용법 + PDF 변환 가이드 (Pandoc / 한컴오피스 / Typora 안내)
+- `viewer-server.ts` 주석 — 데모 표현 제거, 운영 위치 명시
+- README badge `tools` 88 → 92
+
+### Rationale
+
+본질 우선순위 (사용자 황룡 2026-05-21 명시): **(1) 온톨로지 그래프 기반 작성 보조와 가이드라인 (2) 완성 문서 검토 (3) A2UI 가 작성자에게 필요한 정보를 능동적으로 가져올 수 있도록 LLM 과 연결**. ADR 002 가 세 본질을 동시 충족. ADR 001 의 viewer 격상은 14,000 안전관리자 (SAM 5,400사) 도달 — Agent_HQ PHILOSOPHY §9 의 Human fallback / 직원 역할 항목 해소. 이슈 5건 fix 는 npm 첫 publish 후 사용자 onboarding 마찰 직접 해소.
+
 ## [1.3.1] — 2026-05-20
 
 **npm 첫 publish 직후 patch — version 시점 정합**
@@ -40,7 +275,7 @@ v1.3.0 npm publish 후 git tag 가 가리키는 commit 과 publish 된 commit
 ### 안전관리자가 받는 실질 가치
 
 - **88개 도구** 모두 작성 보조 직접 동작
-- **1,039 KOSHA Guide 본문 번들** (offline, keyless — 인터넷 없이 가이드 발췌)
+- **1,037 KOSHA Guide 본문 번들** (offline, keyless — 인터넷 없이 가이드 발췌)
 - **8개 법령 본문 번들** (산안법·시행령·시행규칙·기준규칙·중처법·중처법 시행령·위험성평가 고시·건진법 §62 영역)
 - **19종 법정문서 그래프 추론 14/14** (100%)
 - **도구별 결과 일관성 보장** (같은 docId 어느 도구로 호출해도 결과 같음)
@@ -70,7 +305,7 @@ Claude Desktop / OpenAI Codex CLI 두 host 메인 지원. `npm` 한 줄.
 ### 핵심 자료
 
 - 88 MCP tools
-- 1,039 KOSHA Guide 본문 (offline, MD 형식)
+- 1,037 KOSHA Guide 본문 (offline, MD 형식)
 - 8개 법령 본문 (offline)
 - 94 docId 마스터 + 132 form index
 - 3,336 노드 운영 그래프 (작업·위험·통제·법령·문서·증빙·조치·보고)
@@ -85,7 +320,7 @@ Claude Desktop / OpenAI Codex CLI 두 host 메인 지원. `npm` 한 줄.
 
 - 코드: MIT
 - 안전관리 법령 본문: 저작권법 §7 비보호 (자유 인용)
-- KOSHA Guide 본문 (1,039건): 공공누리 출처표시·변경금지
+- KOSHA Guide 본문 (1,037건): 공공누리 출처표시·변경금지
 
 ### 제공·개발
 

package/NOTICE.md

@@ -68,7 +68,9 @@ and is not required for you to preserve when forking or redistributing
 the code. It is provided so that downstream consumers who wish to
 credit the project correctly have the canonical citation:
 
-- **Provider**: 황룡건설(주) 안전보건기획부 — 도메인 검증·현장 요구사항·시나리오 제공
+- **Provider**: 황룡건설(주) (Hwangryong Construction Co., Ltd.) 안전보건기획부 — 도메인 검증·현장 요구사항·시나리오 제공
+  - 대표자: 황한일
+  - 주소: 충청남도 아산시 염치읍 충무로431번길 9 (9, Chungmu-ro 431beon-gil, Yeomchi-eup, Asan-si, Chungcheongnam-do, Republic of Korea)
 - **Developer**: 주식회사 라텔웍스 (Ratelworks Inc.) — <alphamale@ratelworks.co.kr>
 - **Purpose**: Public-interest open source — improving accessibility of
   Korean public safety-and-health resources for front-line workers and

package/README-EN.md

@@ -2,7 +2,7 @@
 
 > An OSS MCP server that gives AI Agents (**Claude Desktop / OpenAI Codex CLI**) **safety-management domain expertise** by providing Korean construction-safety **statutes, KOSHA Guides, and other public data as an ontology graph**.
 >
-> Helps safety managers and site managers draft **19 statutory safety documents** (TBM logs, work plans, risk assessments, MSDS registers, accident reports, etc.) accurately and quickly. Bundles **8 statute MDs** (OSH Act/Decree/Rule, Safety Rules, SAPA, SAPA Decree, Risk Assessment Notice, CTPA §62 area) + **1,039 KOSHA Guides** + other public data (Law Information Center, KOSHA, MOEL, MOLIT) unified in a single ontology graph. Provides forms, fill-in guides, statute body excerpts, and review at the moment of drafting. **The safety manager remains the author; the MCP is a co-pilot.**
+> Helps safety managers and site managers draft **<!-- INV:DOCUMENTS_TOTAL -->19<!-- /INV:DOCUMENTS_TOTAL --> statutory safety documents** (TBM logs, work plans, risk assessments, MSDS registers, accident reports, etc.) accurately and quickly. Bundles **<!-- INV:LAW_BUNDLE_COUNT -->8<!-- /INV:LAW_BUNDLE_COUNT --> statutes — curated key articles, not full text** (<!-- INV:LAW_ARTICLES -->76<!-- /INV:LAW_ARTICLES --> articles total — per-statute breakdown in [`docs/INVENTORY.md §4`](./docs/INVENTORY.md), auto-generated) + **<!-- INV:KOSHA_BODY -->1,039<!-- /INV:KOSHA_BODY --> KOSHA Guide bodies + <!-- INV:KOSHA_META -->1,039<!-- /INV:KOSHA_META --> graph metadata** (<!-- INV:KOSHA_FAILURES -->0<!-- /INV:KOSHA_FAILURES --> bodies unavailable from KOSHA OneAPI — listed in [`docs/INVENTORY.md`](./docs/INVENTORY.md), kordoc-extracted, quality-tiered verified/partial/raw) + other public data (Law Information Center, KOSHA, MOEL, MOLIT) unified in a single ontology graph. Provides forms, fill-in guides, statute body excerpts, and review at the moment of drafting. **The safety manager remains the author; the MCP is a co-pilot.**
 >
 > [Korean README](./README.md) · [Identity](./docs/IDENTITY.md) · [Operational Ontology](./docs/OPERATIONAL-ONTOLOGY.md) · [Claude Desktop Setup](./docs/SETUP_CLAUDE_DESKTOP.md) · [Codex CLI Setup](./docs/SETUP_CODEX.md) · [Quality Report](./docs/QUALITY-REPORT.md)
 
@@ -10,16 +10,16 @@
 
 | Item | Current code |
 |---|---:|
-| Package version | **1.3.1** (2026-05-20) |
-| MCP tools | **88** (offline-first, single API key for 6 KOSHA Live tools) |
+| Package version | **<!-- INV:VERSION -->1.5.0<!-- /INV:VERSION -->** (2026-05-23) |
+| MCP tools | **<!-- INV:TOOLS_TOTAL -->92<!-- /INV:TOOLS_TOTAL -->** (offline-first, API key needed for <!-- INV:TOOLS_KEYREQ -->7<!-- /INV:TOOLS_KEYREQ --> KOSHA Live tools) |
 | Statutory documents | **19** (TBM, work plans, risk assessments, MSDS, accident reports, etc.) |
-| Legal-duty document master | 94 docIds |
-| Full guides | 19 |
-| Form index | 132 formIds (HWP 14 / PDF 23 / XLSX 1 / MD 94) |
-| Operational graph | 3,336 nodes / 29,642 edges |
-| Core activity/hazard/control nodes | WorkActivity 41 / Hazard 38 / Control 45 |
-| Bundled statutes | **8 MDs**: OSH Act, OSH Decree, OSH Rule, Safety Rules, SAPA, SAPA Decree, Risk Assessment Notice, CTPA §62 area |
-| Bundled KOSHA Guides | **1,039 bodies** (offline, keyless, kordoc-extracted) |
+| Legal-duty document master (`legal-duty-master.json`) | **<!-- INV:DOCID_MASTER -->94<!-- /INV:DOCID_MASTER -->** docIds (19 statutes + cycle/scope/issuer variants) |
+| Full guides | <!-- INV:DOCUMENTS_TOTAL -->19<!-- /INV:DOCUMENTS_TOTAL --> |
+| Form index (`forms-map.json`) | **<!-- INV:FORMS_TOTAL -->132<!-- /INV:FORMS_TOTAL -->** formIds (HWP <!-- INV:FORMS_HWP -->14<!-- /INV:FORMS_HWP --> / PDF <!-- INV:FORMS_PDF -->23<!-- /INV:FORMS_PDF --> / XLSX <!-- INV:FORMS_XLSX -->1<!-- /INV:FORMS_XLSX --> / MD <!-- INV:FORMS_MD -->94<!-- /INV:FORMS_MD -->) |
+| Operational graph | **<!-- INV:GRAPH_TOTAL -->3,369<!-- /INV:GRAPH_TOTAL -->** nodes (recursive, KOSHA Guide <!-- INV:KOSHA_META -->1,039<!-- /INV:KOSHA_META --> included) / ~<!-- INV:GRAPH_EDGES -->32,963<!-- /INV:GRAPH_EDGES --> edges. Top-level category nodes: <!-- INV:GRAPH_TOPLEVEL -->2,212<!-- /INV:GRAPH_TOPLEVEL --> |
+| Core activity/hazard/control nodes | WorkActivity <!-- INV:GRAPH_ACTIVITIES -->41<!-- /INV:GRAPH_ACTIVITIES --> / Hazard <!-- INV:GRAPH_HAZARDS -->38<!-- /INV:GRAPH_HAZARDS --> / Control <!-- INV:GRAPH_CONTROLS -->50<!-- /INV:GRAPH_CONTROLS --> |
+| Bundled statutes | **8 statutes (curated articles, ≈77 articles total)**: OSH Act 10/175, Decree 3/159, Rule 4/252, Safety Rules 10/671, SAPA 7/16, SAPA Decree 13/14, Risk Assessment Notice 23/23 (full), CTPA §62 area 4 — full breakdown in `docs/INVENTORY.md` |
+| Bundled KOSHA Guides | **<!-- INV:KOSHA_BODY -->1,039<!-- /INV:KOSHA_BODY --> bodies + <!-- INV:KOSHA_META -->1,039<!-- /INV:KOSHA_META --> metadata** (<!-- INV:KOSHA_FAILURES -->0<!-- /INV:KOSHA_FAILURES --> bodies unavailable, offline, keyless, kordoc-extracted) |
 | Verification | `ontology:operational` 38/38, `mcp:test:graph` pass, `audit:strict` pass |
 | Field scenarios | 4/4 scenarios, 29/29 steps, quality average 8.65/10 |
 
@@ -92,16 +92,17 @@ The LLM does not invent statutory basis. Laws, hazards, controls, and document l
 
 ## Install
 
-> **Current status**: not yet published to npm registry (`npm view agent-safety-oss` returns E404). Use the "From source" path below. The npm command will work after publishing a future release.
+> **Current status**: v<!-- INV:VERSION -->1.5.0<!-- /INV:VERSION --> published on npm (`npm view agent-safety-oss version` → `<!-- INV:VERSION -->1.5.0<!-- /INV:VERSION -->`). Both paths below work.
 
 ```bash
-# After npm publish
+# Recommended — npm-published binary
+npx -y agent-safety-oss tools
+npx -y agent-safety-oss serve
+# Or install globally
 npm install -g agent-safety-oss
-agent-safety-oss tools
-agent-safety-oss serve
 ```
 
-From source (current path):
+From source (developers / fork):
 
 ```bash
 git clone https://github.com/ratelworks/agent-safety-oss.git
@@ -170,13 +171,13 @@ Run `npm run mcp:tools` for the full catalog.
 ```bash
 npm install
 npm run build
-npm run mcp:demo:viewer
+npm run mcp:viewer
 # → http://localhost:5174 starts automatically
 ```
 
-Pick a form type (TBM log, excavation work plan, periodic risk assessment, etc.) and the page renders with blanks, examples, and statutory references already populated.
+Pick a form type (TBM log, excavation work plan, periodic risk assessment, etc.) and the page renders with blanks, examples, and statutory references already populated. Fill in, generate the document body, archive, and download as `.md` — all in one page.
 
-For a static-only preview (paste JSONL into a textarea, no server), see [`a2ui-demo/README.md`](./a2ui-demo/README.md).
+> For PDF output, convert the downloaded `.md` via [Pandoc](https://pandoc.org/), Hangul/HWP Office, or [Typora](https://typora.io/).
 
 ## Verification
 
@@ -200,7 +201,8 @@ Recent verification:
 
 ## Provider · Developer
 
-- **Provider**: 황룡건설(주) Safety & Health Planning Dept. — domain validation, on-site requirements, and scenarios
+- **Provider**: 황룡건설(주) (Hwangryong Construction Co., Ltd.) Safety & Health Planning Dept. — domain validation, on-site requirements, and scenarios
+  - CEO: Hwang Han-il (황한일) · Address: 9, Chungmu-ro 431beon-gil, Yeomchi-eup, Asan-si, Chungcheongnam-do, Republic of Korea
 - **Developer**: Ratelworks Inc. — MCP server design/implementation, OSS maintenance, public safety data accessibility. <alphamale@ratelworks.co.kr>
 
 ## Awards & Recognition