deuk-agent-rule 2.2.2 → 2.3.2

package/CHANGELOG.ko.md

@@ -0,0 +1,48 @@
+# 변경 이력 (Changelog)
+
+이 프로젝트의 모든 주목할 만한 변경 사항은 이 파일에 기록됩니다.
+
+**English:** [CHANGELOG.md](CHANGELOG.md)
+
+형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 기반으로 하며, 이 프로젝트는 [유의적 버전(Semantic Versioning)](https://semver.org/spec/v2.0.0.html)을 준수합니다.
+
+## [2.3.2] - 2026-04-17
+
+### 수정됨 (Fixed)
+
+- **cli:** 배포 환경에서 하드코딩된 `yaml` 의존성 경로 문제(`ERR_MODULE_NOT_FOUND`) 해결
+- **dependencies:** `yaml`을 명시적 의존성 목록에 추가
+
+## [2.3.0] - 2026-04-17
+
+### 추가됨 (Added)
+
+- AI 파이프라인 연동 기반 및 선택적 동기화 시스템 고도화
+- **cli:** ticket list 명령에 --submodule 필터 추가
+- **cli:** 티켓 아카이브 및 리포트 워크플로를 모듈형 아키텍처로 복구
+- **rules:** Unity Client, WebApp, C++ 서버 하이브리드 환경을 위한 룰 고도화
+- **ticket:** 분산형 티켓 관리 및 공유 정책 구현
+- **ticket:** V2 YAML Front-matter 및 카테고리화된 리스트로 업그레이드
+
+### 수정됨 (Fixed)
+
+- **ticket:** LATEST.md를 폐기하고 ACTIVE_TICKET.md로 포인터 통일
+- **ticket:** DeukAgentRules 현재 진행 중인 티켓 안 나오던 문제 해결
+
+## [1.0.14] - 2026-04-02
+
+### 추가됨 (Added)
+
+- **cli:** 병합 도구 및 배포 문서 동기화 스크립트 확장
+- **rules:** 커밋 제목 내 'sync' 금지 구문 룰 추가
+- **handoff:** 인덱스 기반 Handoff 워크플로 및 CLI 신설
+- **architecture:** 제로-터치 NPM 번들 스캐폴딩으로 템플릿 아키텍처 개편
+
+### 수정됨 (Fixed)
+
+- **cli:** 템플릿 생성기(init) 내부의 HTML 엔티티 문법 에러 핫픽스
+
+### 변경됨 (Changed)
+
+- **docs:** 외부 공개용 릴리즈 가이드 및 동기화 스크립트 주석 갱신
+- **docs:** 리드미(README)에 토큰 비용 차단 메커니즘 설정 및 제로 터치 스캐폴딩 문서 개편

package/CHANGELOG.md

@@ -2,154 +2,197 @@
 
 All notable changes to this project will be documented in this file.
 
+**한글:** [CHANGELOG.ko.md](CHANGELOG.ko.md)
+
 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.0.18] - 2026-04-12
-
-
-### Added
-
-- **ai:** map conversational ticket requests to implicit CLI execution
-- **cli:** implement ticket archive and reporting workflow
-- **rules:** map conversational ticket aliases to implicit CLI execution
-
-
-### Changed
-
-- **readme:** add ticket archive and reports CLI usage to documentation
-- **readme:** describe natural language CLI prompting alternatives
-- **readme:** provide explicit conversational prompt examples inside option tables
-- **readme:** provide explicit update guide
-- **rules:** add prompting guide and execution report archival rule
-
-## [1.0.17] - 2026-04-06
-
-
-### Fixed
-
-- **template:** move ticket repo-relative marker to bottom
-
-## [1.0.16] - 2026-04-05
-
-
-### Added
-
-- **workflow:** add auto-verification and final report to agent workflows
-
-## [1.0.15] - 2026-04-05
-
-
-### Added
-
--  migrate and rename handoff terminology to ticket in CLI and templates
-
-
-### Changed
-
--  Add strict rule for DeukPack namespace requirement
--  completely eradicate legacy Handoff references from AGENTS.md, templates, and mdc rules
--  Enforce DeukPack code format and API strictly as a hard rule
--  refactor README usage guide and workflow
-
-## [1.0.14] - 2026-04-02
-
-
-### Added / 추가됨
-
-- **cli:** extend merge tooling and sync publish docs / 병합 도구 및 배포 문서 동기화 스크립트 확장
-- **rules:** forbid 'sync' word in commit titles in agent rules / 커밋 제목 내 'sync' 금지 구문 룰 추가
-- **handoff:** add indexed handoff workflow and CLI / 인덱스 기반 Handoff 워크플로 및 CLI 신설
-- **architecture:** migrate template architecture to zero-touch NPM bundle scaffolding / 제로-터치 NPM 스캐폴딩으로 템플릿 아키텍처 개편
-
-
-### Fixed / 수정됨
-
-- **cli:** resolve html entity syntax error in template generator / 템플릿 생성기(init) 내부의 HTML 엔티티 문법 에러 핫픽스
-
-
-### Changed / 변경됨
-
-- **docs:** public-facing RELEASING and changelog wording; sync-bundle comment / 외부 공개용 릴리즈 가이드 및 동기화 스크립트 주석 갱신
-- **docs:** update README with token efficiency mechanism and zero-touch template scaffolding / 리드미(README)에 토큰 비용 차단 메커니즘 설정 및 제로 터치 스캐폴딩 문서 개편
-
-## [1.0.13] - 2026-03-28
-
-
-### Fixed
-
-- **deuk-agent-rule:** `printHandoffTip` missing in CLI (handoff tip after `init`)
-
-
-### Changed
-
-- **docs:** README § Handoffs; GitHub About text; npm keywords; CLI survey adds Claude, Windsurf, JetBrains AI Assistant
-- **agents:** optional `.cursor/plans/*.plan.md` mirror for plan-style UI; chat `Path:` line and optional first-line path in handoff files
-- **deuk-agent-rule:** `init` prints a short handoff tip after ensuring `.deuk-agent-handoff/`
-- **deuk-agent-rule:** default `--rules prefix` overwrites existing `deuk-agent-rule-*.mdc` on repeat `init` (package updates without a separate `merge`)
-- **deuk-agent-rule:** `.deuk-agent-rule.config.json` stores interactive choices; later `init` reuses them (`--interactive` to change; `--non-interactive` for CI only)
-
-
-## [1.0.12] - 2026-03-27
-
-
-### Fixed
-
-- **ci:** release workflow runs on pushes to `master`
-
-### Changed
-
-- **agents:** require full repo-root paths for handoff file links
-
-## [1.0.11] - 2026-03-26
-
-
-### Added
-
-- **ci:** GitHub Release workflow for version tags and `chore(release):` commits on `main` / `master`
-
-## [1.0.10] - 2026-03-26
-
-
-### Added
-
-- **deuk-agent-rule:** changelog template headers without per-commit links
-
-## [1.0.9] - 2026-03-27
-
-### Added
-
-- **deuk-agent-rule:** release changelog tooling; handoff directory gitignore; pre-work handoff scan; AGENTS inject newline fix
-
-### Changed
-
-- **agents:** DeukAgentRules/handoff/LATEST.md handoff path for consumer repos
-
-## [1.0.8] - 2026-03-27
-
-### Added
-
-- This changelog and npm `files` entry so releases are traceable.
-
-## [1.0.7] - 2026-03-27
-
-### Added
-
-- `init`: create `.deuk-agent-handoff/` and append `.gitignore` rules for local handoffs.
-- CLI: pre-work handoff scan; `publish/AGENTS.md` and `multi-ai-workflow.mdc` updates.
-
-### Fixed
-
-- AGENTS tagged-region merge: trailing newline after injected blocks.
-
-## [1.0.5] - 2026-03-26
-
-### Changed
-
-- README and package metadata (Deuk Family tagline, npm keywords, GitHub Topics note).
-
-## [1.0.4] - 2026-03-26
-
-### Changed
-
-- Release packaging includes `package-lock.json` for reproducible installs.
-- README: absolute links for the npm package page.
+## [2.3.2] - 2026-04-17
+
+
+### Fixed
+
+- **cli:** resolve `ERR_MODULE_NOT_FOUND` in distributed environments by fixing hardcoded `yaml` dependency path
+- **dependencies:** add `yaml` to explicit dependencies list
+
+## [2.3.1] - 2026-04-17
+
+
+### Changed
+
+- **readme:** add changelog and automated release instructions
+
+## [2.3.0] - 2026-04-17
+
+
+### Added
+
+- Advance AI pipeline integration and optional synchronization system
+- **cli:** add --submodule filter to ticket list command
+- **cli:** restore ticket archive and reports workflows to modular architecture
+- **rules:** advance rules for Unity Client, WebApp, and C++ Server hybrid environment
+- **ticket:** implementation of decentralized ticket management & sharing policy
+- **ticket:** upgrade to V2 YAML Front-matter and Categorized List
+
+
+### Fixed
+
+- **ticket:** deprecate LATEST.md, unify pointer to ACTIVE_TICKET.md
+- **ticket:** resolve issue where active tickets were not listed for DeukAgentRules repo
+
+
+### Changed
+
+- **readme:** clarify YAML front matter preservation and distributed ticket workflow for v2.2.2
+- **readme:** restore count headers and npm badges
+- **rules:** enforce CLI usage for ticket reading to prevent manual JSON parsing
+- Update CLI reference with close and migrate commands
+
+## [1.0.18] - 2026-04-12
+
+
+### Added
+
+- **ai:** map conversational ticket requests to implicit CLI execution
+- **cli:** implement ticket archive and reporting workflow
+- **rules:** map conversational ticket aliases to implicit CLI execution
+
+
+### Changed
+
+- **readme:** add ticket archive and reports CLI usage to documentation
+- **readme:** describe natural language CLI prompting alternatives
+- **readme:** provide explicit conversational prompt examples inside option tables
+- **readme:** provide explicit update guide
+- **rules:** add prompting guide and execution report archival rule
+
+## [1.0.17] - 2026-04-06
+
+
+### Fixed
+
+- **template:** move ticket repo-relative marker to bottom
+
+## [1.0.16] - 2026-04-05
+
+
+### Added
+
+- **workflow:** add auto-verification and final report to agent workflows
+
+## [1.0.15] - 2026-04-05
+
+
+### Added
+
+- Migrate and rename handoff terminology to ticket in CLI and templates
+
+
+### Changed
+
+- Add strict rule for DeukPack namespace requirement
+- Completely eradicate legacy Handoff references from AGENTS.md, templates, and mdc rules
+- Enforce DeukPack code format and API strictly as a hard rule
+- Refactor README usage guide and workflow
+
+## [1.0.14] - 2026-04-02
+
+
+### Added
+
+- **cli:** extend merge tooling and sync publish docs
+- **rules:** forbid 'sync' word in commit titles in agent rules
+- **handoff:** add indexed handoff workflow and CLI
+- **architecture:** migrate template architecture to zero-touch NPM bundle scaffolding
+
+
+### Fixed
+
+- **cli:** resolve html entity syntax error in template generator
+
+
+### Changed
+
+- **docs:** public-facing RELEASING and changelog wording; sync-bundle comment
+- **docs:** update README with token efficiency mechanism and zero-touch template scaffolding
+
+## [1.0.13] - 2026-03-28
+
+
+### Fixed
+
+- **deuk-agent-rule:** `printHandoffTip` missing in CLI (handoff tip after `init`)
+
+
+### Changed
+
+- **docs:** README § Handoffs; GitHub About text; npm keywords; CLI survey adds Claude, Windsurf, JetBrains AI Assistant
+- **agents:** optional `.cursor/plans/*.plan.md` mirror for plan-style UI; chat `Path:` line and optional first-line path in handoff files
+- **deuk-agent-rule:** `init` prints a short handoff tip after ensuring `.deuk-agent-handoff/`
+- **deuk-agent-rule:** default `--rules prefix` overwrites existing `deuk-agent-rule-*.mdc` on repeat `init` (package updates without a separate `merge`)
+- **deuk-agent-rule:** `.deuk-agent-rule.config.json` stores interactive choices; later `init` reuses them (`--interactive` to change; `--non-interactive` for CI only)
+
+
+## [1.0.12] - 2026-03-27
+
+
+### Fixed
+
+- **ci:** release workflow runs on pushes to `master`
+
+### Changed
+
+- **agents:** require full repo-root paths for handoff file links
+
+## [1.0.11] - 2026-03-26
+
+
+### Added
+
+- **ci:** GitHub Release workflow for version tags and `chore(release):` commits on `main` / `master`
+
+## [1.0.10] - 2026-03-26
+
+
+### Added
+
+- **deuk-agent-rule:** changelog template headers without per-commit links
+
+## [1.0.9] - 2026-03-27
+
+### Added
+
+- **deuk-agent-rule:** release changelog tooling; handoff directory gitignore; pre-work handoff scan; AGENTS inject newline fix
+
+### Changed
+
+- **agents:** DeukAgentRules/handoff/LATEST.md handoff path for consumer repos
+
+## [1.0.8] - 2026-03-27
+
+### Added
+
+- This changelog and npm `files` entry so releases are traceable.
+
+## [1.0.7] - 2026-03-27
+
+### Added
+
+- `init`: create `.deuk-agent-handoff/` and append `.gitignore` rules for local handoffs.
+- CLI: pre-work handoff scan; `publish/AGENTS.md` and `multi-ai-workflow.mdc` updates.
+
+### Fixed
+
+- AGENTS tagged-region merge: trailing newline after injected blocks.
+
+## [1.0.5] - 2026-03-26
+
+### Changed
+
+- README and package metadata (Deuk Family tagline, npm keywords, GitHub Topics note).
+
+## [1.0.4] - 2026-03-26
+
+### Changed
+
+- Release packaging includes `package-lock.json` for reproducible installs.
+- README: absolute links for the npm package page.

package/README.ko.md

@@ -1,4 +1,13 @@
-# DeukAgentRules (득에이전트룰스)
+<div align="center">
+  <br />
+  <h1>DeukAgentRules (득에이전트룰스)</h1>
+  <p>
+    <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/v/deuk-agent-rule.svg" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/dt/deuk-agent-rule.svg" alt="npm downloads" /></a>
+  </p>
+  <p><b>고신호(High-Signal) 인코딩 & 규칙 표준화 엔진</b></p>
+  <p><a href="https://deukpack.app">Deuk Family</a> 생태계의 핵심 에이전트 인프라</p>
+</div>
 
 > **Deuk Family**의 핵심 모듈 가운데 하나입니다. 구조화된 규칙으로 AI 에이전트의 협업 효율을 극대화합니다.
 
@@ -10,7 +19,7 @@ Cursor, GitHub Copilot, Gemini / Antigravity, Claude, Windsurf, JetBrains AI Ass
 프로젝트 규칙(`AGENTS.md`, `.cursor/rules`)을 표준화하고, **티켓 기반 워크플로우**를 통해 쓸데없는 프롬프트 토큰 낭비와 AI의 맥락 환각(Hallucination)을 강력하게 방어합니다.
 
 > **🚀 핵심 가치:**
-> 세션당 약 1,500~2,000 토큰에 달하는 강제 로드 컨텍스트를 200~300 토큰 수준으로 압축합니다. AI가 모놀리식 전체 레포지토리를 헤매지 않도록, 정확한 티켓(작업 지시서) 기반으로 **"해당 서브모듈(Submodule)"**에만 격리시켜 작업을 지시할 수 있습니다.
+> 세션당 약 1,500~2,000 토큰에 달하는 강제 로드 컨텍스트를 200~300 토큰 수준으로 압축합니다. AI가 모놀리식 전체 레포지토리를 헤매지 않도록, 작업이 속한 **"해당 서브모듈(Submodule)"** 내부에 티켓을 격리하여 가장 정확한 맥락에서 작업을 지시할 수 있습니다.
 
 ---
 
@@ -23,7 +32,8 @@ npm install deuk-agent-rule
 npx deuk-agent-rule init
 ```
 
-초기화 시 프로젝트의 **기술 스택**과 **사용 중인 에이전트 툴**을 묻는 대화형 질문이 나타나며, 선택에 맞춰 최적화된 마크다운 템플릿과 룰 파일(`.cursor/rules/*`)들이 자동 생성 및 동기화됩니다. 
+초기화 시 프로젝트의 **기술 스택**, **사용 중인 에이전트 툴**, 그리고 **티켓 공유 정책**을 묻는 대화형 질문이 나타납니다. 
+- **티켓 공유 정책**: 각 저장소 단위의 `.deuk-agent-ticket/` 폴더를 Git으로 추적하여 팀과 공유할지, 아니면 로컬 전용으로 둘지 결정합니다.
 - 스택 변경이 필요 없으면 이후에는 `npx deuk-agent-rule init`만 쳐서 규칙을 최신화할 수 있습니다.
 - CI나 스크립트 환경에서는 대화형 입력을 끄기 위해 `--non-interactive` 파라미터를 추가하세요.
 
@@ -37,22 +47,26 @@ npx deuk-agent-rule init --non-interactive
 
 ---
 
-## 🎯 핵심 워크플로우 (The Ticket Workflow)
+## 🎯 핵심 워크플로우 (The Distributed Ticket Workflow)
 
-`npx deuk-agent-rule init`을 실행하면 워크스페이스 최상단에 **제로-터치 스캐폴딩 샌드박스**가 작동하며 아래 두 개의 핵심 폴더가 등장합니다. 
+`npx deuk-agent-rule init`을 실행하면 현재 저장소 루트(서브모듈 포함)에 아래 두 개의 핵심 폴더가 등장합니다. 
 
-1. **`.deuk-agent-templates/` (에이전트 템플릿)**: AI가 어떠한 양식으로 작업을 처리하고 보고해야 하는지 정의된 공식 뼈대(`TICKET_TEMPLATE.md`)가 지정됩니다. 소스코드와 함께 Git에 커밋되어 팀의 룰북 역할을 합니다.
-2. **`.deuk-agent-ticket/` (티켓 실행 공간)**: 에이전트들과 작업자가 실제 주고받는 휘발성 지시서(`TICKET-XXX.md`)가 발급되는 은밀한 공간입니다. (보안 및 히스토리 누출 방지를 위해 시스템이 자동으로 `.gitignore`에 기재합니다.)
+1. **`.deuk-agent-templates/` (에이전트 템플릿)**: AI가 어떠한 양식으로 작업을 처리하고 보고해야 하는지 정의된 공식 뼈대(`TICKET_TEMPLATE.md`)가 지정됩니다.
+2. **`.deuk-agent-ticket/` (티켓 실행 공간)**: 실제 지시서(`TICKET-XXX.md`)가 발급되는 공간입니다. 서브모듈 단위로 티켓을 분산 관리할 수 있어 서브모듈만 떼어가도 히스토리가 유지됩니다. (공유 정책에 따라 `.gitignore`에 자동으로 기재될 수 있습니다.)
 
 이러한 샌드박스 폴더들을 활용하여 스퍼트를 올리는 **최적의 AI 코딩 3단계**는 다음과 같습니다.
 
-### [Step 1] 티켓 발급 및 서브모듈 지정 (Ticket Creation)
-AI에게 중구난방으로 지시하지 마세요. 명확한 티켓을 발급하여 **문맥(Context)을 좁혀주어야** 비용과 사고를 막을 수 있습니다.
+### [Step 1] 티켓 발급 및 계층적 관리 (Ticket Creation & Delegation)
+AI에게 중구난방으로 지시하지 마세요. 명확한 티켓을 발급하여 **문맥(Context)을 소속 저장소 단위로 좁혀주어야** 합니다.
 
 ```bash
-npx deuk-agent-rule ticket create --topic ui-refactoring --group frontend --project DeukUI --content "## Task: 플러그인 UI 리팩토링"
+npx deuk-agent-rule ticket create --topic ui-refactoring --group frontend --project DeukUI
 ```
 명령어를 치면 `.deuk-agent-ticket/` 폴더 내에 템플릿이 입혀진 `TICKET-ui-refactoring.md` 파일이 생성됩니다.
+
+> [!IMPORTANT]
+> **티켓 작성 (주의사항)**: 새로 생성된 티켓에는 **YAML Front Matter** (`--- id: ... ---`)가 포함되어 있습니다. 내용을 작성할 때 **파일 전체를 덮어쓰지 마십시오.** 반드시 헤더 아래에 내용을 추가하거나 부분 편집 도구를 사용하여 기존 YAML 메타데이터를 보존해야 합니다. 프론트매터가 삭제되면 티켓 인덱싱 시스템이 파손됩니다.
+
 개발자는 이 파일 내의 `[Target Submodule]` 속성에 AI가 들여다보아야 할 고립된 경로(예: `src/client`)만을 명시해 줍니다.
 
 ### [Step 2] 세션 인수인계 및 에이전트 격리 실행 (Agent Execution)
@@ -91,7 +105,7 @@ npx deuk-agent-rule ticket list
 > *"본격적인 작업을 시작하기 전에 워크스페이스 Root에 있는 `AGENTS.md` (DeukAgentRules) 문서를 끝까지 읽어줘. 현재 프로젝트의 핵심 룰, Identity, 그리고 티켓 워크플로우에 대해 완벽히 숙지해야 해. 숙지를 마쳤다면 내용을 요약하지 말고 '규칙 확인 완료'라고 짧게 대답한 뒤 첫 지시를 대기해."*
 
 ### 2. 티켓 기반 타깃 작업 시작 (권장)
-> *"방금 발급된 `.deuk-agent-ticket/TICKET-XXX.md` 티켓을 열고, 티켓 내부에 명시된 **타겟 서브모듈(Target Submodule)** 경로 내에서만 파일 탐색 및 작업을 진행해. 다른 서브모듈(예: 서버 코드를 명시했는데 클라이언트 폴더를 건드리는 행위 등)로 벗어나거나 임의의 파일을 건드리지 마."*
+> *"방금 설치/발급된 `.deuk-agent-ticket/TICKET-XXX.md` 티켓을 열고, 현재 저장소(Target Submodule) 경로 내에서만 파일 탐색 및 작업을 진행해. 다른 서브모듈로 벗어나거나 임의의 파일을 건드리지 마."*
 
 ---
 
@@ -104,13 +118,13 @@ npx deuk-agent-rule ticket list
 
 | 커맨드 | 설명 / 자연어 프롬프트 지시 예시 |
 |--------|------|
-| `npx deuk-agent-rule ticket create ...` | 신규 티켓 문서 생성 (`--group`, `--project` 지정 가능) <br>💬 *"새 티켓 만들어 (주제: refactor, 타겟: sub1)"* |
-| `npx deuk-agent-rule ticket list` | 활성 티켓의 현재 상태 및 리스트업 (`--archived`, `--all` 지원) <br>💬 *"티켓 리스트"* |
+| `npx deuk-agent-rule ticket create ...` | 신규 티켓 문서 생성 (`--group`, `--project`, `--submodule` 지정 가능) <br>💬 *"새 티켓 만들어 (주제: refactor, 타겟: sub1)"* |
+| `npx deuk-agent-rule ticket list` | 활성 티켓의 현재 상태 및 리스트업 (`--archived`, `--all`, `--json` 지원) <br>💬 *"티켓 리스트"* |
 | `npx deuk-agent-rule ticket use --latest ...` | 빌드 파이프라인 연동을 위해 최근 티켓의 파일 경로만 반환 <br>💬 *"최근 티켓 경로"* |
 | `npx deuk-agent-rule ticket close ...` | 파일을 물리적으로 이동시키지 않고 상태만 완료로 잠금(Soft-close) <br>💬 *"현재 티켓 상태 닫아 (완료)"* |
+| `npx deuk-agent-rule ticket upgrade` | 과거 티켓 구조를 V2(YAML FM)로 마이그레이션 및 서브모듈 분산(DEFRAG) 실행 <br>💬 *"티켓 V2 업그레이드"* |
 | `npx deuk-agent-rule ticket archive ...` | 완료된 티켓을 안전하게 보관소(`archive/`)로 이동 및 갱신 <br>💬 *"현재 티켓 아카이브해 (보고서 첨부)"* |
 | `npx deuk-agent-rule ticket reports` | 영구 보관된 에이전트 작업 보고서(`reports/`) 목록 조회 <br>💬 *"완료된 티켓 보고서 목록"* |
-| `npx deuk-agent-rule ticket migrate` | 과거 단일 LATEST.md 데이터를 신규 모듈형 인덱스 구조로 강제 이전 <br>💬 *"이전 티켓 데이터 마이그레이션"* |
 
 ### Init 고급 옵션
 | 플래그 | 기본값 | 설명 |
@@ -121,5 +135,15 @@ npx deuk-agent-rule ticket list
 | `--dry-run` | 끔 | 실제 파일을 생성/변조하지 않고 콘솔에 동작 결과 텍스트만 출력 |
 | `--backup` | 끔 | `AGENTS.md`나 룰 파일 덮어쓰기 전 원본을 `*.bak`으로 안전 보관 |
 
-## 버전 관리 정책
-본 패키지(`DeukAgentRules`)의 업데이트 및 기능 변경 전에는 필히 `package.json`의 `version` 상향 후 퍼블리시(`npm run sync:oss`) 해 주시기 바랍니다.
+## 📦 릴리즈 및 체인지로그 (Changelog) 정책
+
+본 패키지(`DeukAgentRules`)의 시스템 템플릿 추가 및 기능 변경을 배포하기 전에 반드시 다음 절차를 따라 릴리즈 프로세스를 진행해야 합니다:
+
+1. **변경사항 커밋**: 문서 및 룰 스크립트 수정 완료 후 `git add` & `git commit` (Conventional Commits 형식 권장, ex: `feat: ...`, `fix: ...`)
+2. **버전 펌핑 및 체인지로그 자동 생성**:
+   * Patch (버그 수정): `npm run bump:patch`
+   * Minor (기능 추가): `npm run bump:minor`
+   * Major (룰/템플릿 대격변): `npm run bump:major`
+   
+   위 명령어를 실행하면 내부적으로 `commit-and-tag-version` 툴이 작동되어 `package.json` 버전 상향, `CHANGELOG.md` 자동 갱신 요약, 릴리즈 커밋, 그리고 태깅 작업까지 한번에 즉시 처리됩니다.
+3. **분산 배포 보정 (OSS Sync)**: 에이전트를 통해 `npm run sync:oss`를 실행하면 자동화 스크립트가 릴리즈 에셋을 스캔하여 OSS 미러 저장소(`DeukAgentRulesOSS`)로 최종적인 퍼블리시 버전을 복제 및 반영합니다.

package/README.md

@@ -1,4 +1,13 @@
-# DeukAgentRules
+<div align="center">
+  <br />
+  <h1>DeukAgentRules</h1>
+  <p>
+    <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/v/deuk-agent-rule.svg" alt="npm version" /></a>
+    <a href="https://www.npmjs.com/package/deuk-agent-rule"><img src="https://img.shields.io/npm/dt/deuk-agent-rule.svg" alt="npm downloads" /></a>
+  </p>
+  <p><b>High-Signal Encoding & Rule Standardization Engine</b></p>
+  <p>Part of the <a href="https://deukpack.app">Deuk Family</a> ecosystem.</p>
+</div>
 
 > A core module of the **Deuk Family**. Maximizes collaboration efficiency of AI agents through structured rules.
 
@@ -50,9 +59,13 @@ The optimal **3-Step AI Coding Sequence** utilizing these sandbox folders is as
 Do not issue scattered, unbounded commands to your AI. Narrowing the **context** via a clear ticket is strictly required to prevent astronomical costs and accidental code corruption.
 
 ```bash
-npx deuk-agent-rule ticket create --topic ui-refactoring --group frontend --project DeukUI --content "## Task: Plugin UI Refactoring"
+npx deuk-agent-rule ticket create --topic ui-refactoring --group frontend --project DeukUI
 ```
 This command instantly creates a templated `TICKET-ui-refactoring.md` file within the `.deuk-agent-ticket/` directory.
+
+> [!IMPORTANT]
+> **Filling the Ticket (CRITICAL)**: The newly created ticket already contains **YAML Front Matter** (`--- id: ... ---`). **DO NOT** overwrite the entire file when adding your plan. ALWAYS append your content below the header or use partial file editing to preserve the existing YAML metadata. Erasing the Front Matter corrupts the ticketing system.
+
 The developer must simply specify the exact isolated directory path (e.g., `src/client`) inside the `[Target Submodule]` attribute at the top of the generated file.
 
 ### [Step 2] Agent Execution & Handoff (Ticket Session)
@@ -104,13 +117,13 @@ Instead of manually typing the CLI commands below into the terminal, you can **d
 
 | Command | Description / Natural Language Prompt Example |
 |--------|------|
-| `npx deuk-agent-rule ticket create ...` | Generates a new ticket document (accepts `--group`, `--project`) <br>💬 *"Create new ticket (topic: refactor)"* |
-| `npx deuk-agent-rule ticket list` | Lists and displays active tickets (`--archived`, `--all` supported) <br>💬 *"Ticket list"* |
+| `npx deuk-agent-rule ticket create ...` | Generates a new ticket document (accepts `--group`, `--project`, `--submodule`) <br>💬 *"Create new ticket (topic: refactor)"* |
+| `npx deuk-agent-rule ticket list` | Lists and displays active tickets (`--archived`, `--all`, `--json` supported) <br>💬 *"Ticket list"* |
 | `npx deuk-agent-rule ticket use --latest ...` | Returns only the file path of the most recent ticket <br>💬 *"Recent ticket path"* |
 | `npx deuk-agent-rule ticket close ...` | Soft-closes a target ticket by locking its status to completed without moving the file <br>💬 *"Close this ticket"* |
+| `npx deuk-agent-rule ticket upgrade` | Migrates legacy ticket structures to V2 (YAML FM) and triggers submodule DEFRAG <br>💬 *"Upgrade tickets to v2"* |
 | `npx deuk-agent-rule ticket archive ...` | Securely moves completed tickets to `archive/` and updates INDEX <br>💬 *"Archive this ticket (attach report)"* |
 | `npx deuk-agent-rule ticket reports` | Lists structurally preserved agent work reports (`reports/`) <br>💬 *"List archived reports"* |
-| `npx deuk-agent-rule ticket migrate` | Migrates legacy LATEST.md structures into indexed module architecture <br>💬 *"Migrate legacy tickets"* |
 
 ### Advanced Init Options
 | Flag | Default | Description |
@@ -121,5 +134,15 @@ Instead of manually typing the CLI commands below into the terminal, you can **d
 | `--dry-run` | Off | Simulates the execution text in the console without generating/altering files |
 | `--backup` | Off | Safely creates `*.bak` copies of `AGENTS.md` and rule files before overwriting |
 
-## Versioning Policy
-Before pushing any core updates/feature changes to this package (`DeukAgentRules`), strictly bump the `version` inside `package.json` and publish it (`npm run sync:oss`).
+## 📦 Release & Changelog Policy
+
+Before pushing any core updates, system templates, or feature changes to this package (`DeukAgentRules`), you must strictly follow this procedure to bump the version safely:
+
+1. **Apply Changes**: Complete documentation and rule script updates, then `git add` and `git commit` (Conventional Commits format recommended, e.g., `feat: ...`, `fix: ...`).
+2. **Version Bump & Automated Changelog**:
+   * Patch (Bug fixes): `npm run bump:patch`
+   * Minor (New features): `npm run bump:minor`
+   * Major (Core/Breaking changes): `npm run bump:major`
+   
+   Executing the bump command will trigger the `commit-and-tag-version` pipeline: it bumps the version in `package.json`, auto-generates the `CHANGELOG.md` log, creates a release commit, and applies the release tag.
+3. **Synchronize & Mirror (OSS Sync)**: As a final step, ask your agent to run `npm run sync:oss`. The automation script will clean the release assets and push the bundled versions to the mirror repository (`DeukAgentRulesOSS`).