@neobiotechlabs/neobiotech-dev-agent 0.1.8 → 0.1.10

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
         "source": "npm",
         "package": "@neobiotechlabs/neobiotech-dev-agent",
         "registry": "https://registry.npmjs.org",
-        "version": "0.1.8"
+        "version": "0.1.10"
       },
       "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.8",
+  "version": "0.1.10",
   "displayName": "NeoBiotech Dev Agent (MedDev)",
   "description": "의료기기 SW 규제 개발 자동화 — Jira·Confluence·Risk·CVSS·Xray·IEC 62304/62366·MDR·문서 렌더",
   "author": {

package/README.md

@@ -1,205 +1,186 @@
 # @neobiotechlabs/neobiotech-dev-agent
 
-IEC 62304 의료기기 소프트웨어 개발을 위한 Jira MCP Server. Claude Code에서 Jira, Confluence, Risk Management, CVSS, Xray, 추적성 관리를 직접 사용할 수 있습니다.
+IEC 62304 의료기기 소프트웨어 개발을 위한 MCP Server. Claude Code에서 Jira, Confluence, Risk Management, CVSS, Xray, 추적성 관리를 직접 사용합니다. **npm-as-plugin**으로 배포되어 `/plugin install` 한 번으로 MCP 서버 등록 + doc-render skill 배포 + 인증(userConfig → 키체인)이 한 번에 처리됩니다.
 
-## 사전 설정
+> 서버 자체를 개발/수정하는 분은 [docs/developer-guide.md](docs/developer-guide.md)를, 전체 툴 레퍼런스는 이 문서 아래쪽을 참고하세요.
 
-공개 npm 패키지(npmjs.org)로 게시되어 별도 registry 인증 없이 아래 설치 명령으로 바로 사용할 수 있습니다.
+## 설치 (plugin — 권장)
 
-## 설치
+공개 npm(npmjs.org)에 게시되어 별도 registry 인증 없이 설치할 수 있습니다. Claude Code 안에서:
 
-```bash
-# 글로벌 설치 (추천)
-npm install -g @neobiotechlabs/neobiotech-dev-agent
-
-# 또는 매번 최신 버전 실행 (설치 불필요)
-npx -y @neobiotechlabs/neobiotech-dev-agent
 ```
+1) marketplace 등록 (GitHub source — 누구나 가능)
+   /plugin marketplace add NeobiotechLabs/jira-mcp-server
 
-업데이트:
-```bash
-npm update -g @neobiotechlabs/neobiotech-dev-agent
-```
+2) plugin 설치 (user scope 권장 — 어느 프로젝트에서든 적용)
+   /plugin install neobiotech-dev-agent@neobiotech
 
-베타 테스트:
-```bash
-npm install -g @neobiotechlabs/neobiotech-dev-agent@beta
+3) 자격증명 입력 (키체인에 저장)
+   /plugin configure neobiotech-dev-agent@neobiotech
+
+4) Claude Code 완전 재시작 → /mcp 에서 neobiotech-dev-agent 가 ✔ Connected 인지 확인
 ```
 
-## 로컬 빌드 (개발/브랜치 테스트용)
+`userConfig` 6개 항목 (3번 configure 시 입력):
+
+| 항목 | 필수 | 비고 |
+|------|------|------|
+| `JIRA_URL` | O | **https 권장** — http에선 node-fetch 리다이렉트가 POST를 GET으로 변환해 생성/수정이 실패함 |
+| `JIRA_EMAIL` | O | Jira 계정 이메일 |
+| `JIRA_API_TOKEN` | O | [발급](https://id.atlassian.com/manage-profile/security/api-tokens) |
+| `XRAY_CLIENT_ID` | X | Xray Cloud (둘 다 있어야 활성화) |
+| `XRAY_CLIENT_SECRET` | X | Xray Cloud |
+| `RISK_PLUGIN_AUTH_TOKEN` | X | Risk Management Plugin |
+
+> ⚠️ 재시작 없으면 userConfig가 반영되지 않아 spawn 직후 종료됩니다 (`/mcp`에서 `-32000`). 설치/구성 후 **반드시 Claude Code를 완전히 재시작**하세요.
+> ⚠️ 설치·업데이트 후에도 옛날 버전이 실행된다면 consumer 로컬 캐시가 원인입니다 — [트러블슈팅](#트러블슈팅) 참고.
+
+## 로컬에서 코드 변경하며 테스트
 
-소스 코드를 직접 빌드하여 사용할 수도 있습니다:
+서버 코드를 고치면서 바로 확인하려는 경우(서버 개발·브랜치 테스트) 두 가지 패턴이 있습니다. 어떤 패턴이든 **watch + `/mcp` reconnect** 루프가 핵심입니다.
+
+### 준비 (공통): clone + build
 
 ```bash
-# submodule 포함 clone 권장 (doc_render 툴이 vendor/dev-docs-templates/ 사용)
+# doc_render 툴이 vendor/dev-docs-templates/ submodule을 쓰므로 --recurse-submodules
 git clone --recurse-submodules https://github.com/NeobiotechLabs/jira-mcp-server.git
 cd jira-mcp-server
 npm install
-npm run build
+npm run build        # dist/index.js 단일 bundle (최초 1회 필수 — dist는 git에 없음)
 ```
 
-이미 clone한 경우 submodule을 별도로 초기화:
-
-```bash
-git submodule update --init --recursive
-```
+이미 clone한 경우: `git submodule update --init --recursive`.
 
-## Claude Code 설정
+### 패턴 1: `claude mcp add`로 로컬 빌드 직접 실행 (빠른 iteration, 권장)
 
-### 방법 1: `claude mcp add` 명령어
+빌드된 `dist/index.js`를 MCP 서버로 바로 등록합니다. plugin의 userConfig/키체인 대신 환경변수를 직접 주고, 가장 빠르게 코드를 돌려볼 수 있습니다.
 
-**npm 패키지 설치 시:**
+한 터미널에서 watch를 켜둡니다 — 소스 저장 시 `dist/`가 자동 재빌드됩니다:
 
 ```bash
-claude mcp add jira \
-  -e JIRA_URL=https://your-domain.atlassian.net \
-  -e JIRA_EMAIL=your-email@example.com \
-  -e JIRA_API_TOKEN=your-api-token \
-  -- npx -y @neobiotechlabs/neobiotech-dev-agent
+npm run dev
 ```
 
-**로컬 빌드 시:**
+다른 터미널에서 (또는 Claude Code 세션에서) 로컬 dist를 MCP 서버로 등록:
 
 ```bash
-claude mcp add jira \
+claude mcp add neobiotech-dev --scope user \
   -e JIRA_URL=https://your-domain.atlassian.net \
   -e JIRA_EMAIL=your-email@example.com \
   -e JIRA_API_TOKEN=your-api-token \
-  -- node /절대경로/jira-mcp-server/dist/index.js
+  -- node "$(pwd)/dist/index.js"
 ```
 
-선택 환경 변수도 함께 추가할 수 있습니다:
+> `-e` 옵션은 `--` 앞에 와야 합니다. Xray/Risk가 필요하면 같은 방식으로 `-e XRAY_CLIENT_ID=...` 등 추가.
 
-```bash
-  -e XRAY_CLIENT_ID=... \
-  -e XRAY_CLIENT_SECRET=... \
-  -e RISK_PLUGIN_AUTH_TOKEN=... \
-  -- npx -y @neobiotechlabs/neobiotech-dev-agent
-```
+코드를 고칠 때마다 반영: **Claude Code `/mcp` → `neobiotech-dev` → reconnect**.
 
-**주의:** `-e` 옵션은 `--` 앞에 와야 합니다.
+> stdio MCP 서버는 프로세스가 시작될 때 코드를 메모리에 로드합니다. watch가 `dist/`를 갱신해도 프로세스를 재시작(reconnect)하지 않으면 옛날 코드를 계속 씁니다. "즉시 반영"의 마지막 단계는 항상 reconnect입니다.
 
-### 방법 2: `~/.claude/settings.json` 직접 편집
+### 패턴 2: plugin을 로컬 directory source로 설치
 
-**패키지 설치 시:**
+plugin의 userConfig/키체인/doc-render skill 배포 이점을 그대로 쓰면서 로컬 코드를 실행하려면, `.claude-plugin/marketplace.json`의 source를 배포용 npm 대신 로컬 directory로 임시 교체합니다.
 
-```json
-{
-  "mcpServers": {
-    "jira": {
-      "command": "npx",
-      "args": ["-y", "@neobiotechlabs/neobiotech-dev-agent"],
-      "env": {
-        "JIRA_URL": "https://your-domain.atlassian.net",
-        "JIRA_EMAIL": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-api-token",
-        "XRAY_CLIENT_ID": "",
-        "XRAY_CLIENT_SECRET": "",
-        "RISK_PLUGIN_AUTH_TOKEN": ""
-      }
-    }
-  }
-}
-```
-
-**로컬 빌드 시:**
+`.claude-plugin/marketplace.json`의 `plugins[0].source`를 임시로 변경:
 
 ```json
-{
-  "mcpServers": {
-    "jira": {
-      "command": "node",
-      "args": ["/절대경로/jira-mcp-server/dist/index.js"],
-      "env": {
-        "JIRA_URL": "https://your-domain.atlassian.net",
-        "JIRA_EMAIL": "your-email@example.com",
-        "JIRA_API_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
+"source": { "source": "directory", "path": "." }
+```
+
+그리고:
+
+```
+/plugin marketplace add /절대경로/jira-mcp-server
+/plugin install neobiotech-dev-agent@neobiotech --scope user
 ```
 
-### 방법 3: 프로젝트 `.mcp.json` 사용
+코드 변경 반영은 동일하게 `/mcp` reconnect. 검증이 끝나면 `git checkout .claude-plugin/marketplace.json`으로 복구. 변경 전 `claude plugin validate .`로 매니페스트 정합성을 확인하세요.
 
-각 프로젝트 루트에 `.mcp.json`과 `.env` 파일을 만들면, 프로젝트별로 설정을 관리할 수 있습니다.
+> plugin(`/plugin install`)과 `claude mcp add`는 서버 이름이 다르면 공존하지만 헷갈리므로, 번갈아 쓸 때는 한쪽을 제거(`claude plugin uninstall` 또는 `claude mcp remove`) 후 전환을 권장합니다.
 
-**`.mcp.json`** (git에 커밋):
+## 프로젝트 초기 설정
+
+각 consumer 프로젝트 폴더에서 최초 1회 실행하면, 이후 모든 툴이 해당 Jira 프로젝트 키를 자동으로 인식합니다.
 
-```json
-{
-  "mcpServers": {
-    "jira": {
-      "command": "npx",
-      "args": ["-y", "@neobiotechlabs/neobiotech-dev-agent"],
-      "env": {
-        "JIRA_URL": "${JIRA_URL}",
-        "JIRA_EMAIL": "${JIRA_EMAIL}",
-        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
-      }
-    }
-  }
-}
 ```
+jira 프로젝트 초기 설정해줘. 프로젝트 키는 DYN야
+```
+
+→ `jira_init_project` → `./CLAUDE.md`에 키를 기록. 여러 프로젝트면 폴더마다 각각 실행.
+
+## 트러블슈팅
+
+### 설치·업데이트 후 옛날 버전이 실행됨 (stale)
+
+`uninstall` → `install` 해도 같은 버전이 계속 잡힌다면, 두 군데 중 한 곳이 stale한 것입니다. **비파괴적 방법부터 먼저** 시도합니다.
 
-**`.env`** (개인 설정, git에 커밋하지 않음):
+**1. marketplace 갱신 먼저** (비파괴적 — 항상 먼저):
 
 ```
-JIRA_URL=https://your-domain.atlassian.net
-JIRA_EMAIL=your-email@example.com
-JIRA_API_TOKEN=your-api-token
+/plugin marketplace update neobiotech
+/reload-plugins
 ```
 
-## 환경 변수
+이것만으로 marketplace.json이 최신 version을 가리키게 되면 install이 최신 버전을 잡습니다. (`/plugin marketplace update`가 안 먹으면 `/plugin marketplace remove neobiotech` 후 `/plugin marketplace add NeobiotechLabs/jira-mcp-server`로 git clone을 강제 fresh — 공식 known issue [#38271](https://github.com/anthropics/claude-code/issues/38271).)
 
-| 변수 | 필수 | 설명 |
-|------|------|------|
-| `JIRA_URL` | O | Jira 인스턴스 URL (**https 권장** — http에선 node-fetch 리다이렉트가 POST를 GET으로 변환해 생성/수정이 실패함) |
-| `JIRA_EMAIL` | O | Jira 계정 이메일 |
-| `JIRA_API_TOKEN` | O | Jira API 토큰 ([발급](https://id.atlassian.com/manage-profile/security/api-tokens)) |
-| `XRAY_CLIENT_ID` | X | Xray Cloud client ID |
-| `XRAY_CLIENT_SECRET` | X | Xray Cloud client secret |
-| `RISK_PLUGIN_AUTH_TOKEN` | X | Risk Management Plugin 인증 토큰 |
-| `PROJECT_CONFIG_PATH` | X | (사용하지 않음) |
+**2. 여전히 옛날 버전이면 npm-cache 정리** (마지막 수단) — Claude Code를 **완전히 종료한 뒤**:
 
-## 릴리즈 절차
+```bash
+rm -rf ~/.claude/plugins/npm-cache                       # stale package-lock + node_modules
+rm -rf ~/.claude/plugins/cache/neobiotech                # 옛날 installPath 잔해
+rm -f  ~/.claude/plugins/plugin-catalog-cache.json       # stale marketplace snapshot (있으면)
+```
+
+재시작 후 `/plugin marketplace update neobiotech` → `/plugin install neobiotech-dev-agent@neobiotech`.
 
-### 정식 릴리즈
+### 다른 PC에서 `No matching version` (npm registry / `.npmrc`)
+
+Windows 등 **다른 PC**에서 `/plugin install` 시 `failed to install npm packages. No matching version` 으로 실패하면, npmjs.org와 패키지는 정상이고 **해당 PC의 npm 설정이 원인**입니다. plugin install이 `.claude-plugin/marketplace.json`에 적은 `registry`(`https://registry.npmjs.org`)보다 **시스템 `.npmrc`를 우선** 사용하기 때문입니다. 사내 npm mirror를 기본으로 쓰거나, 이전 install 실패로 `.npmrc`에 잘못된 줄(쓰레기)이 쌓여 있으면 npmjs.org 대신 다른 registry를 쿼리합니다.
+
+진단:
 
 ```bash
-# 1. main 브랜치에서
-npm version patch   # 0.1.0 → 0.1.1 (또는 minor, major)
-git push --follow-tags
-# → GitHub Actions가 자동으로 npm(npmjs.org)에 latest로 publish
+npm config get registry                                                        # npmjs.org가 아니면 원인
+npm view @neobiotechlabs/neobiotech-dev-agent@0.1.8 version --registry https://registry.npmjs.org   # 버전이 나오면 패키지·npmjs.org 정상 → 이 PC의 .npmrc 문제 확정
 ```
 
-### 베타 릴리즈
+해결 — `%USERPROFILE%\.npmrc`(Windows) / `~/.npmrc`(macOS·Linux)에서 이전 실패로 쌓인 쓰레기 줄(잘못된 registry · scope · auth 잔재)을 전체 삭제한 뒤, scope registry 오버라이드 추가:
 
-```bash
-# 1. main 브랜치에서 베타 버전 생성
-npm version prerelease --preid=beta
-# → 0.1.0 → 0.1.1-beta.0
+```
+@neobiotechlabs:registry=https://registry.npmjs.org/
+```
 
-git push --follow-tags
-# → GitHub Actions가 자동으로 npm(npmjs.org)에 beta로 publish
+사내 mirror를 전역 기본으로 유지해야 하면 **scope 오버라이드만**으로 충분합니다. **Claude Code 완전 재시작** 후 `/plugin install neobiotech-dev-agent@neobiotech` 재시도. 상세 진단 순서는 [developer-guide §10.7](docs/developer-guide.md#107-트러블슈팅).
 
-# 2. 테스터가 설치
-npm install -g @neobiotechlabs/neobiotech-dev-agent@beta
+### `/mcp`에서 `Failed to connect` / `-32000` (plugin)
 
-# 3. 테스트 완료 후 정식 릴리즈
-npm version patch   # 0.1.1-beta.0 → 0.1.1
-git push --follow-tags
-# → latest로 publish, beta 사용자는 npm update로 자동 업그레이드
+두 원인:
+
+1. **userConfig 미구성 (가장 흔함)** — install 직후 userConfig(키체인)가 비어 `.mcp.json`의 `${user_config.*}`가 빈 값 → `src/index.ts`가 필수 env 검증에서 `process.exit(1)`. `/plugin configure`로 값을 넣고 **Claude Code 완전 재시작**.
+2. **runtime 의존성 누락 (과거)** — 0.1.8 tsup bundle 도입으로 해결. 최신 버전이면 해당 없음.
+
+진단 — installPath의 `dist/index.js`를 직접 실행해 봅니다:
+
+```bash
+node ~/.claude/plugins/cache/neobiotech/neobiotech-dev-agent/<version>/dist/index.js </dev/null
+# "Missing JIRA_URL..."  → 모듈 로딩 통과 = 원인 1 (userConfig)
+# ERR_MODULE_NOT_FOUND   → bundle 누락 = 옛날 버전 (원인 2)
 ```
 
-### 태그별 dist-tag 매핑
+### `claude mcp add` 모드 연결 실패
+
+가장 흔한 원인은 args 경로 오타 또는 빌드 누락. `claude mcp get <name>`으로 `Command`/`Args`/`Environment`를 점검하고, `ls <경로>`로 파일이 실제 존재하는지 확인 (없으면 `npm run build`).
 
-| git 태그 | npm dist-tag | 설치 명령어 |
-|----------|-------------|-------------|
-| `v0.1.1-beta.0` | `beta` | `npm i -g @neobiotechlabs/neobiotech-dev-agent@beta` |
-| `v0.1.1` | `latest` | `npm i -g @neobiotechlabs/neobiotech-dev-agent` |
+### 일반
 
-## 툴 목록 (48개)
+| 증상 | 원인 / 해결 |
+|------|------------|
+| `Missing environment variables...`로 종료 | 필수 env 3개 중 하나라도 비면 `index.ts`가 `process.exit(1)`. `claude mcp get`의 env 또는 userConfig에서 값 누락 확인 |
+| Risk / Xray 툴이 동작 안 함 | 선택 env(`RISK_PLUGIN_AUTH_TOKEN`, `XRAY_*`) 누락/만료. `xray`는 두 env가 모두 있어야 활성화 |
+| `401`/`403` | 토큰/권한. Jira API 토큰 재발급, 프로젝트 권한·이슈타입 존재 여부 확인 |
+| 프로젝트 키가 인식 안 됨 | `jira_init_project` 미실행. consumer `CLAUDE.md`에 키가 있는지 확인 |
+
+## 툴 목록 (49개)
 
 ### Jira 기본 CRUD (12)
 
@@ -218,7 +199,7 @@ git push --follow-tags
 | `jira_delete_issue` | 이슈 삭제 |
 | `jira_get_issue_type_schema` | 이슈 타입의 필드 스키마 동적 조회 |
 
-### Confluence (7)
+### Confluence (8)
 
 | 툴 | 설명 |
 |-----|------|
@@ -229,6 +210,7 @@ git push --follow-tags
 | `confluence_delete_page` | 페이지 삭제 |
 | `confluence_get_spaces` | 스페이스 목록 |
 | `confluence_get_page_children` | 하위 페이지 조회 |
+| `confluence_publish_doc` | **(High-level)** 마크다운 문서 → Confluence 페이지 게재 (create/update 자동 분기, 마크다운 → storage 변환 + 코드펜스 → 코드 매크로) |
 
 ### Risk Management (5)
 
@@ -309,7 +291,7 @@ IEC 62304 추적성 관리.
 
 | 툴 | 설명 |
 |-----|------|
-| `doc_render` | dev_docs(PRD/Spec/Plan/Tasks)·mdr_docs(intended-use) 템플릿 모드 기반(freeform) 결정적 렌더 — 메타만 치환, 자유 텍스트/AI 지침은 consumer가 채움 |
+| `doc_render` | dev_docs(PRD/Spec/Plan/Tasks)·mdr_docs(PA/EA gate 문서 전체) 템플릿 모드 기반(freeform) 결정적 렌더 — 메타만 치환, 자유 텍스트/AI 지침/빈 데이터 표는 consumer가 채움 |
 
 ### 초기 설정 (1)
 
@@ -319,57 +301,23 @@ IEC 62304 추적성 관리.
 
 ## doc_render 작성 skill (consumer 워크플로우)
 
-이 서버는 `.claude/skills/doc-render/` 절차 가이드를 함께 제공한다. consumer(Claude Code)가 doc_render 출력으로 MDR/dev 문서를 자동 작성해 자기 repo `docs/`에 저장하고 Jira 티켓 description에 미러한다.
-
-### 설치 (수동 copy)
-
-이 repo의 `.claude/skills/doc-render/` 를 consumer 프로젝트의 `.claude/skills/doc-render/` 로 복사:
-
-```bash
-cp -R <이-repo>/.claude/skills/doc-render <consumer-repo>/.claude/skills/
-```
+이 서버는 `.claude/skills/doc-render/` 절차 가이드를 함께 제공합니다. `/plugin install` 하면 consumer(Claude Code)에게 skill도 자동으로 배포되므로, consumer는 doc_render 출력으로 MDR/dev 문서를 자동 작성해 자기 repo `docs/`에 저장하고 Jira 티켓 description에 미러할 수 있습니다.
 
-### 사용
+> plugin이 아닌 `claude mcp add` 모드를 쓸 때만 skill을 수동으로 복사합니다:
+> ```bash
+> cp -R <이-repo>/skills/doc-render <consumer-repo>/.claude/skills/
+> ```
 
 consumer Claude Code 세션에서:
 
 > "DYN-8 intended use 문서 작성"
 
-skill이 doc_render 호출 → 자동 초안 → 리뷰 게이트 → `docs/mdr/PA/intended-use-DYN-8.md` 저장 → DYN-8 description 미러까지 수행한다. 자세한 절차·저장 경로·frontmatter 스키마는 [`skills/doc-render/SKILL.md`](skills/doc-render/SKILL.md) 와 [설계 문서](docs/superpowers/specs/2026-07-03-doc-render-skill-design.md) 참조.
-
-> 이 서버는 **npm-as-plugin**으로 배포됩니다 — `/plugin install neobiotech-dev-agent@neobiotech` 한 번으로 MCP 서버 자동 등록 + doc-render skill 자동 배포 + userConfig(키체인) 인증이 처리됩니다. 설치 절차는 [docs/developer-guide.md §3 / §10](docs/developer-guide.md) 참조.
-
-## 프로젝트 초기 설정
-
-각 프로젝트 폴더에서 최초 1회 실행:
-
-```
-jira_init_project(project_key: "SCW")
-```
-
-→ `CLAUDE.md`에 프로젝트 키가 자동 추가되어, 이후 Claude가 모든 툴에서 해당 키를 자동으로 사용합니다.
-
-사용 예시:
-
-```
-# Claude Code 안에서
-jira 프로젝트 초기 설정해줘. 프로젝트 키는 SCW야
-```
-
-또는 여러 프로젝트를 진행할 경우, 각 프로젝트 폴더에서 별도로 초기 설정:
-
-```
-# A 프로젝트 폴더
-jira_init_project(project_key: "SCW")
-
-# B 프로젝트 폴더
-jira_init_project(project_key: "NEO")
-```
+skill이 doc_render 호출 → 자동 초안 → 리뷰 게이트 → `docs/mdr/PA/intended-use-DYN-8.md` 저장 → DYN-8 description 미러까지 수행합니다. 자세한 절차·저장 경로·frontmatter 스키마는 [`skills/doc-render/SKILL.md`](skills/doc-render/SKILL.md)와 [설계 문서](docs/superpowers/specs/2026-07-03-doc-render-skill-design.md) 참조.
 
 ## 사용 예시
 
 ```
-PLAYG-1234 이슈 내용 알려줘
+DYN-1234 이슈 내용 알려줘
 ```
 → `jira_get_issue`
 
@@ -384,7 +332,7 @@ Hazard 티켓 2개 만들어줘. [HAZ-1] 영상 렌더링 오류, [HAZ-2] 측정
 → `cvss_calculate` + `cvss_set_vector`
 
 ```
-PLAYG-2550의 추적성 확인해줘
+DYN-2550의 추적성 확인해줘
 ```
 → `traceability_check`
 
@@ -437,6 +385,31 @@ EA Gate
       └── 선행 Task ── Blocks ──→ 후행 Task
 ```
 
+## 릴리즈 절차
+
+배포는 **`v*` 태그 push** 시 GitHub Actions(`release.yml`)이 자동 수행(build → test → publish to npmjs.org, 공개). main에 머지만 해서는 배포되지 않습니다.
+
+### 정식
+
+```bash
+npm version patch && git push --follow-tags      # latest (version lifecycle가 plugin.json/marketplace.json 자동 동기화)
+```
+
+### 베타
+
+```bash
+npm version prerelease --preid=beta && git push --follow-tags     # beta (태그명에 beta 포함 시 --tag beta)
+```
+
+> consumer(이미 plugin 설치한 팀원)의 업데이트는 `/plugin marketplace update neobiotech` 후 `/plugin install` 재실행. stale 캐시가 잡고 있으면 [트러블슈팅](#트러블슈팅)의 캐시 정리 절차를 따르세요.
+
+### 태그별 dist-tag 매핑
+
+| git 태그 | npm dist-tag | consumer 설치 |
+|----------|-------------|---------------|
+| `v0.1.9-beta.0` | `beta` | marketplace.json source.version을 beta로 맞추거나 `/plugin marketplace update` |
+| `v0.1.9` | `latest` | `/plugin install neobiotech-dev-agent@neobiotech` (캐시 정리 후) |
+
 ## 라이선스
 
 MIT