deuk-agent-rule 3.3.2 → 3.3.3

package/CHANGELOG.ko.md

@@ -6,6 +6,13 @@
 
 형식은 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/)를 기반으로 하며, 이 프로젝트는 [유의적 버전(Semantic Versioning)](https://semver.org/spec/v2.0.0.html)을 준수합니다.
 
+## [3.3.3] - 2026-05-06
+
+### 수정됨 (Fixed)
+
+- npm과 GitHub 첫 화면에서 영어/한국어 README를 바로 오갈 수 있도록 언어 전환 링크를 복구했습니다.
+- README 문서 표에는 공개 문서 링크만 남기고, 내부 리서치와 성장 전략 문서는 npm/OSS 공개 표면에서 제외했습니다.
+
 ## [3.3.2] - 2026-05-06
 
 ### 포지셔닝 (Positioning)

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be 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).
 
+## [3.3.3] - 2026-05-06
+
+### Fixed
+
+- Restored the README language switch links so npm and GitHub readers can move between English and Korean documentation from the first screen.
+- Published only public documentation links in the README tables while keeping internal research and growth notes out of the npm/OSS surface.
+
 ## [3.3.2] - 2026-05-06
 
 ### Positioning

package/README.ko.md

@@ -2,7 +2,7 @@
   <br />
   <img src="docs/assets/architecture-v3.png" width="800" alt="DeukAgentRules Architecture" />
   <br />
-  <h1>DeukAgentRules v3.3.2</h1>
+  <h1>DeukAgentRules v3.3.3</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>
@@ -10,6 +10,7 @@
   <p><b>모든 레포를 위한 AI 코딩 에이전트 가드레일</b></p>
   <p><i>Codex, Copilot, Claude Code, Cursor를 위한 티켓, 범위 계약, 검증, 기억 계층</i></p>
   <p><a href="https://deukpack.app">Deuk Family</a> 생태계의 핵심 모듈입니다.</p>
+  <p><a href="README.md">English</a> · <a href="README.ko.md">한국어</a></p>
 </div>
 
 ---
@@ -21,7 +22,7 @@
 티켓 관리는 `.deuk-agent/` 아래에서 이뤄지며, 진행 중인 작업은 `.deuk-agent/tickets/`에, 관련 문서와 계획, 아카이브 정보도 그 주변 구조에 함께 쌓입니다.
 
 > **현재 배포 기준:**
-> v3.3.2는 에이전트 기반 리포지토리에 배포해 사용할 수 있는 상태입니다. 현재는 **OpenAI Codex**와 **GitHub Copilot** 환경에서 가장 안정적으로 동작합니다. Cursor, Windsurf, Claude Code, MCP도 포인터 구조로 지원하지만, 워크스페이스별 검증을 권장합니다. MCP 서버 등록은 `init`에 딸려 들어가지 않고 별도로 설정합니다.
+> v3.3.3은 에이전트 기반 리포지토리에 배포해 사용할 수 있는 상태입니다. 현재는 **OpenAI Codex**와 **GitHub Copilot** 환경에서 가장 안정적으로 동작합니다. Cursor, Windsurf, Claude Code, MCP도 포인터 구조로 지원하지만, 워크스페이스별 검증을 권장합니다. MCP 서버 등록은 `init`에 딸려 들어가지 않고 별도로 설정합니다.
 
 > **아키텍처 기반:**
 > 거대하고 무거운 레거시 `.cursorrules` 방식을 공식적으로 폐기했습니다. v3.0은 `AGENTS.md`를 단일 진실 공급원으로 사용하는 **Hub-Spoke 모델**을 도입하여, IDE별 규칙은 얇은 진입점 포인터 역할만 수행합니다.
@@ -78,10 +79,6 @@ Karpathy식 skill은 한 작업 안에서 에이전트의 행동을 더 좋게
 | [docs/architecture.ko.md](docs/architecture.ko.md) | 고수준 시스템 구조 및 시각적 인포그래픽 |
 | [docs/how-it-works.ko.md](docs/how-it-works.ko.md) | 상세 CLI 메커니즘, 초기화 생명주기 및 파일 역할 |
 | [docs/principles.ko.md](docs/principles.ko.md) | 설계 철학: Hub-Spoke, Zero-Legacy, 소스 주권 |
-| [docs/product-positioning-research.ko.md](docs/product-positioning-research.ko.md) | AI 코딩 에이전트 가드레일 제품 포지셔닝 리서치 |
-| [docs/karpathy-skills-vs-deukagent-positioning.ko.md](docs/karpathy-skills-vs-deukagent-positioning.ko.md) | Karpathy식 skill, DeukAgentRules, DeukAgentContext 심층 비교 |
-| [docs/vision-agent-guardrails.ko.md](docs/vision-agent-guardrails.ko.md) | 멀티 에이전트 가드레일 허브 비전 문서 |
-| [docs/organic-growth-plan.ko.md](docs/organic-growth-plan.ko.md) | VS Code, Open VSX, GitHub, 스킬 루프 기반 오가닉 유입 계획 |
 | **English Docs** | [README.md](README.md) · [docs/architecture.md](docs/architecture.md) |
 
 ---

package/README.md

@@ -2,7 +2,7 @@
   <br />
   <img src="docs/assets/architecture-v3.png" width="800" alt="DeukAgentRules Architecture" />
   <br />
-  <h1>DeukAgentRules v3.3.2</h1>
+  <h1>DeukAgentRules v3.3.3</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>
@@ -10,6 +10,7 @@
   <p><b>AI coding agent guardrails for every repo</b></p>
   <p><i>Ticketed scope, verification, and memory for Codex, Copilot, Claude Code, Cursor, and more</i></p>
   <p>Part of the <a href="https://deukpack.app">Deuk Family</a> ecosystem.</p>
+  <p><a href="README.ko.md">한국어</a> · <a href="README.md">English</a></p>
 </div>
 
 ---
@@ -21,7 +22,7 @@ It is more than a prompt pack. It is a repository-level workflow layer that stan
 Ticket management lives under `.deuk-agent/`, with active work tracked in `.deuk-agent/tickets/` and related docs, plans, and archive data kept alongside it.
 
 > **Current readiness:**
-> v3.3.2 is deployment-ready for agent-driven repositories. It is currently most reliable in **OpenAI Codex** and **GitHub Copilot** workflows. Cursor, Windsurf, Claude Code, and MCP remain supported through pointer-style integration, but they should be validated per workspace before rollout. MCP server registration is separate from `init`.
+> v3.3.3 is deployment-ready for agent-driven repositories. It is currently most reliable in **OpenAI Codex** and **GitHub Copilot** workflows. Cursor, Windsurf, Claude Code, and MCP remain supported through pointer-style integration, but they should be validated per workspace before rollout. MCP server registration is separate from `init`.
 
 > **Architecture foundation:**
 > We have officially deprecated monolithic `.cursorrules`. v3.0 introduces the **Hub-Spoke model** where `AGENTS.md` is the single source of truth, and IDE-specific rules act as thin entry-point pointers.
@@ -78,10 +79,6 @@ The next step is to make this workflow even easier to see and adopt: clearer fir
 | [docs/architecture.md](docs/architecture.md) | High-level system structure and visual infographics |
 | [docs/how-it-works.md](docs/how-it-works.md) | Detailed CLI mechanics, initialization lifecycle, and file roles |
 | [docs/principles.md](docs/principles.md) | Design philosophy: Hub-Spoke, Zero-Legacy, and Source Sovereignty |
-| [docs/product-positioning-research.ko.md](docs/product-positioning-research.ko.md) | Product positioning research for AI coding agent guardrails |
-| [docs/karpathy-skills-vs-deukagent-positioning.ko.md](docs/karpathy-skills-vs-deukagent-positioning.ko.md) | Deep comparison of Karpathy-style skills, DeukAgentRules, and DeukAgentContext |
-| [docs/vision-agent-guardrails.ko.md](docs/vision-agent-guardrails.ko.md) | Vision document for the multi-agent guardrail hub |
-| [docs/organic-growth-plan.ko.md](docs/organic-growth-plan.ko.md) | Organic growth plan for VS Code, Open VSX, GitHub, and skill loops |
 | **Korean Docs** | [README.ko.md](README.ko.md) · [docs/architecture.ko.md](docs/architecture.ko.md) |
 
 ---

package/docs/architecture.ko.md

@@ -0,0 +1,34 @@
+# 아키텍처 (v3.0)
+
+DeukAgentRules v3.0은 AI 에이전트 워크플로우의 절대적인 일관성과 효율성을 보장하기 위해 **Hub-Spoke 아키텍처**와 **Global Execution Proxy**를 도입했습니다.
+
+## 1. Zero-Copy Hub-Spoke 아키텍처
+
+v3 모델에서 저장소 루트의 **`AGENTS.md`**는 전역적인 **Global Hub**(단일 진실 공급원, SSoT) 역할을 하며, 프로젝트 최상단의 **`PROJECT_RULE.md`**는 로컬 오버라이드를 담당하는 **Local Hub** 역할을 합니다.
+IDE별 규칙 파일(예: `.cursor/rules/*.mdc`)은 규칙 내용을 복사하지 않고 이 허브들을 가리키는 **Spoke**(최소한의 진입점) 역할만 수행하는 Zero-Copy 방식을 사용합니다.
+
+![Hub-Spoke 아키텍처](assets/architecture-v3.png)
+
+### 핵심 원칙
+- **SSoT (Single Source of Truth)**: 모든 범용 운영 규칙은 `AGENTS.md`에 정의되며, 프로젝트 특화 규칙은 `PROJECT_RULE.md`에만 작성됩니다.
+- **경량 Spoke (Zero-Copy)**: IDE 규칙은 내용을 중복해서 담지 않으며, 에이전트가 절대 경로(Absolute Path) 포인터를 통해 Hub를 읽도록 유도합니다.
+- **Zero-Legacy**: `init` 명령은 구세대(v1/v2)의 잔재를 물리적으로 제거하여 깨끗한 상태를 유지합니다.
+- **온라인 RAG 전용**: DeukAgentContext는 로컬 캐시나 또 다른 진실 공급원이 아니라 온라인 보조 기억 계층으로만 사용합니다.
+- **아카이브 보존**: 완료된 작업은 archive/knowledge로 옮겨 활성 context를 작고 최신 상태로 유지합니다.
+
+## 2. Global CLI Proxy (Kind: Src)
+
+`npx` 사용 시 발생하는 '스테일 타르볼(Stale Tarball)' 문제를 해결하기 위해 v3.0은 **Global Proxy**를 구현했습니다.
+
+### 작동 원리:
+1. `npx deuk-agent-rule` 실행 시, 패키지의 글로벌 엔트리 포인트(`bin/deuk-agent-rule.js`)가 구동됩니다.
+2. 현재 디렉터리와 상위 디렉터리를 스캔하여 **로컬 워크스페이스 소스**(`DeukAgentRules/scripts/cli.mjs`)를 자동으로 찾습니다.
+3. 소스가 발견되면 모든 명령을 로컬 소스로 **투명하게 위임(Routing)**합니다.
+4. 이를 통해 에이전트가 레지스트리의 캐시된 버전이 아닌, 현재 개발 중인 최신 로컬 규칙을 항상 사용하도록 보장합니다.
+
+## 3. 초기화 생명주기 (Init Lifecycle)
+
+1. **`migrateLegacyStructure`**: 이전 세대의 디렉터리 구조를 정리하거나 이름을 변경합니다.
+2. **`cleanSubmoduleStubs`**: 빈 서브모듈 스텁과 `.gitmodules`의 고립된 항목을 찾아 제거합니다.
+3. **`deploySpokePointers`**: Hub를 가리키는 경량 Spoke 파일들을 생성합니다.
+4. **`Smart Backup`**: 레거시 `.cursorrules`를 분석하여 사용자 커스텀 규칙이 있을 경우에만 `.bak`을 생성합니다.

package/docs/architecture.md

@@ -0,0 +1,33 @@
+# Architecture (v3.0)
+
+DeukAgentRules v3.0 introduces a **Hub-Spoke Architecture** and a **Global Execution Proxy** to ensure absolute consistency and efficiency in AI-agent workflows.
+
+## 1. Zero-Copy Hub-Spoke Architecture
+
+In the v3 model, **`AGENTS.md`** acts as the global **Hub** (the single source of truth), while **`PROJECT_RULE.md`** serves as the **Local Hub** for project-specific overrides. IDE-specific rule files (e.g., `.cursor/rules/*.mdc`) act as **Spokes** (thin entry points) that use absolute path pointers instead of duplicating rules (Zero-Copy).
+
+![Hub-Spoke Architecture](assets/architecture-v3.png)
+
+### Core Principles
+- **SSoT (Single Source of Truth)**: All operational rules are defined in `AGENTS.md`, and project-specific contexts go into `PROJECT_RULE.md`.
+- **Lightweight Spokes (Zero-Copy)**: IDE rules do not duplicate content; they use absolute paths to point the agent to the Hubs.
+- **Zero-Legacy**: The `init` command aggressively purges obsolete v1/v2 configurations.
+- **Online RAG Only**: DeukAgentContext is used as an online advisory memory layer, not as a local cache or alternate source of truth.
+- **Archive Preservation**: Completed work should move into archive/knowledge so the active context stays small and current.
+
+## 2. Global CLI Proxy (Kind: Src)
+
+To solve the "Stale Tarball" problem common with `npx`, v3.0 implements a **Global Proxy**.
+
+### How it works:
+1. When you run `npx deuk-agent-rule`, the package's global entry point (`bin/deuk-agent-rule.js`) is executed.
+2. It automatically scans the current directory and its parents for a **Local Workspace Source** (`DeukAgentRules/scripts/cli.mjs`).
+3. If found, it **transparently routes** all commands to the local source.
+4. This ensures that agents always use the latest, uncommitted local rules instead of a cached version from the registry.
+
+## 3. Initialization Lifecycle
+
+1. **`migrateLegacyStructure`**: Renames or cleans up old directory patterns.
+2. **`cleanSubmoduleStubs`**: Identifies and removes empty submodule stubs and orphans in `.gitmodules`.
+3. **`deploySpokePointers`**: Generates the thin Spoke files pointing to the Hub.
+4. **`Smart Backup`**: Analyzes legacy `.cursorrules` and creates `.bak` only if custom user rules are detected.

package/docs/how-it-works.ko.md

@@ -0,0 +1,52 @@
+# 작동 원리 (How It Works)
+
+DeukAgentRules는 **AI 엔지니어링 오케스트레이션 프로토콜**로 작동합니다. 중앙 집중식 규칙 허브와 고성능 CLI를 사용하여 에이전트가 코드베이스를 인식, 분석 및 수정하는 방식을 조정합니다.
+
+## 1. Hub-Spoke 실행 모델
+
+v3.0에서 규칙 파일은 더 이상 거대하고 독립적인 형태가 아닙니다. 컨텍스트 팽창을 최소화하기 위해 **Hub-Spoke** 모델을 사용합니다.
+
+- **Hub (`AGENTS.md`)**: 전역적으로 적용되는 중앙 프로젝트 규칙 정본 문서입니다.
+- **Local Hub (`PROJECT_RULE.md`)**: 각 워크스페이스 또는 프로젝트에 특화된 로컬 규칙을 정의하여 전역 허브를 오버라이드합니다.
+- **Spoke (`.cursor/rules/*.mdc` 등)**: 에이전트에게 허브 문서를 읽으라고 지시하는 최소한의 진입점 포인터입니다.
+- **이유**: 이를 통해 에이전트는 서로 다른 IDE 환경에서도 중복이나 오류 없이 항상 최신의 통합된 규칙을 볼 수 있습니다.
+
+## 2. Global CLI Proxy
+
+CLI(`deuk-agent-rule`)는 **소스 주권(Source Sovereignty)** 메커니즘을 사용합니다.
+
+- `npx deuk-agent-rule` 실행 시, 현재 디렉터리 내에 프로젝트 소스 코드가 포함된 워크스페이스가 있는지 확인합니다.
+- 로컬 소스가 감지되면, 실행을 글로벌 바이너리가 아닌 **로컬 스크립트로 라우팅**합니다.
+- 이를 통해 개발 중에 커밋되지 않은 최신 규칙을 에이전트가 즉시 사용할 수 있도록 보장합니다.
+
+## 3. 초기화 생명주기 (Initialization Lifecycle)
+
+`deuk-agent-rule init` 실행 시 다음 과정이 차례로 수행됩니다:
+
+1. **레거시 제거 (Legacy Purge)**: v1/v2 시절의 구형 설정 파일들을 물리적으로 제거합니다.
+2. **서브모듈 진공 청소 (Submodule Vacuum)**: 빈 서브모듈 디렉터리 스텁과 `.gitmodules`의 고립된 항목들을 정리합니다.
+3. **스마트 백업 (Smart Backup)**:
+   - 레거시 파일(`.cursorrules` 등)을 분석합니다.
+   - 사용자 커스텀 규칙이 발견되면 `*.bak` 파일을 생성합니다.
+   - 시스템 생성 내용만 있다면 파일을 즉시 삭제합니다.
+4. **허브 동기화 (Hub Sync)**: 최신 `AGENTS.md`를 배포하고 지원되는 모든 에이전트를 위한 경량 Spoke 파일들을 생성합니다.
+
+## 4. 저장소 역할 및 파일 구조
+
+| 경로 | 역할 |
+|---|---|
+| `AGENTS.md` | 주권적 전역 규칙 허브 (단일 진실 공급원) |
+| `PROJECT_RULE.md` | 로컬 프로젝트 특화 규칙 오버라이드 |
+| `.deuk-agent/config.json` | 프로젝트별 초기화 상태 정보 |
+| `.deuk-agent/tickets/` | 제한된 실행 계약서 (작업 지시서) |
+| `.deuk-agent/templates/` | 티켓 및 플랜 작성을 위한 표준화된 청사진 |
+| `bin/deuk-agent-rule.js` | 글로벌 실행 프록시 |
+
+## 5. 엄격한 Phase 기반 티켓 워크플로우 (TDW)
+
+1. **티켓 발행 (Phase 1)**: `ticket create` 또는 기존 티켓 선택을 통해 타겟 범위를 정의합니다. `--summary`와 `--plan-body`를 함께 써서 채워진 Phase 1 본문을 한 번에 넣고, placeholder 반복을 막고 싶다면 `--require-filled`를 붙입니다. `ticket next`가 진행 가능한 티켓을 찾지 못하면, 후속 티켓을 만들기 전에 최근 git history를 먼저 분석합니다.
+2. **APC 및 메인 티켓 기록**: 에이전트는 코드를 수정하기 전, 메인 티켓에 명시된 APC(Agent Permission Contract)의 `[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`을 채웁니다. 티켓은 스코프/계약/라이프사이클 체크/실행 계획/검증 결과를 맡고, 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 계획 문구에 섞으면 안 됩니다.
+3. **검토 게이트**: 이슈/회귀 보고는 Phase 1 이후 멈춥니다. 사용자가 티켓 계획을 검토한 뒤 실행을 승인해야 하며, 원래 이슈 문장의 "수정", "해결" 같은 표현만으로 검토를 건너뛰면 안 됩니다.
+4. **Phase 승급**: Phase 1 계획이 검토 가능하고 사용자가 실행을 승인하면 `ticket move` 명령을 호출하여 Phase 2 (Execute)로 승급합니다.
+5. **실행 및 검증 (Phase 2)**: 격리된 경계 내에서 코드를 수정하고 검증을 수행합니다.
+6. **지식 증류 아카이빙**: 작업 완료 후 `archive` 시, 핵심 정보만 추출(Zero-Token Distillation)하여 장기 엔지니어링 메모리로 보관합니다.

package/docs/how-it-works.md

@@ -0,0 +1,71 @@
+# How It Works
+
+DeukAgentRules operates as an **AI Engineering Orchestration Protocol**. It coordinates how agents perceive, analyze, and modify your codebase using a centralized rule hub and a high-performance CLI.
+
+## 1. Hub-Spoke Execution Model
+
+In v3.0, rule files are no longer monolithic. We use a **Hub-Spoke** model to minimize context bloat.
+
+- **Global Hub (`AGENTS.md`)**: The central canonical project rule document.
+- **Local Hub (`PROJECT_RULE.md`)**: Project-specific rules that override or augment the global hub.
+- **Spokes (`.cursor/rules/*.mdc`, etc.)**: Minimal entry points that tell the agent to read the Hubs.
+- **Why**: This ensures the agent always sees the latest rules without duplication errors across different IDEs.
+
+## 2. Global CLI Proxy
+
+The CLI (`deuk-agent-rule`) uses a **Source Sovereignty** mechanism.
+
+- When you run `npx deuk-agent-rule`, the binary checks if you are inside a workspace containing the project's source code.
+- If a local source is detected, it **routes execution** to the local script.
+- This ensures that your agents are always using the latest uncommitted rules during development.
+
+## 3. Initialization Lifecycle
+
+Running `deuk-agent-rule init` triggers the following lifecycle:
+
+1. **Legacy Purge**: Physically removes old v1/v2 configuration files.
+2. **Submodule Vacuum**: Cleans up empty submodule directory stubs and orphaned entries in `.gitmodules`.
+3. **Smart Backup**:
+   - Analyzes legacy files (like `.cursorrules`).
+   - If user-added custom rules are found, it creates a `*.bak` file.
+   - If only system-generated content is found, it deletes the file.
+4. **Hub Sync**: Deploys the latest `AGENTS.md` and generates thin Spokes for all supported agents.
+
+## 4. Repository Roles & Files
+
+| Path | Role |
+|---|---|
+| `AGENTS.md` | The Sovereign Rule Hub (Canonical truth) |
+| `PROJECT_RULE.md` | Local project-specific rule overrides |
+| `.deuk-agent/config.json` | Project-specific initialization state |
+| `.deuk-agent/tickets/` | Bounded execution contracts (Work orders) |
+| `.deuk-agent/templates/` | Standardized blueprint for tickets and plans |
+| `bin/deuk-agent-rule.js` | The Global Execution Proxy |
+
+## 5. Strict Phase-Driven Workflow (TDW)
+
+1. **Issue Ticket (Phase 1)**: `ticket create` or an existing ticket defines the target scope. Use `--summary` plus `--plan-body` to place a filled Phase 1 body directly inside the ticket, and prefer `--require-filled` when you want placeholder tickets to fail fast instead of looping. If `ticket next` finds no active/open ticket, inspect recent git history before creating a follow-up ticket.
+2. **APC and Main Ticket Record**: Before modifying code, the agent fills the APC (Agent Permission Contract) blocks `[BOUNDARY]`, `[CONTRACT]`, and `[PATCH PLAN]` inside the main ticket. The main ticket owns scope, contract, lifecycle checks, execution planning, and verification outcomes. Never move execution logs, command transcripts, completion summaries, or verification results into planning prose.
+3. **Review Gate**: Issue/regression reports stop after Phase 1. The user reviews the ticket plan before execution; wording such as "fix" or "resolve" in the original issue is not approval to skip review.
+4. **Phase Transition**: After the Phase 1 plan is reviewable and the user approves execution, run `ticket move` to transition to Phase 2 (Execute).
+5. **Execute & Verify (Phase 2)**: Changes are made and verified within the isolated boundary.
+6. **Knowledge Distillation Archive**: When archiving, core information is extracted (Zero-Token Distillation) to save context tokens for long-term memory.
+
+## 6. Ticket Files in Git
+
+Ticket files are part of the repository workflow, but they should not be handled like ordinary handwritten notes.
+
+- Commit `.deuk-agent/tickets/INDEX*.json` together with the related ticket markdown changes. Leaving index updates behind can break state restoration in the next session.
+- Treat ticket markdown under `.deuk-agent/tickets/**/*.md` as CLI-owned artifacts. If `ticket create` fails, do not create or repair the file manually.
+- Editing ticket body content is fine while planning, but lifecycle state changes should go through `ticket move`, `ticket close`, and `ticket archive`, not direct frontmatter edits.
+- `telemetry.jsonl` is typically operational output rather than durable project state. Unless your repository intentionally tracks it, keep it out of ordinary code commits.
+- Prefer committing finished work after `ticket archive` so the ticket file move and archive index update stay in the same Git change.
+- When reviewing Git changes, first ask whether each ticket-related diff came from an expected CLI lifecycle step. If not, reconcile with CLI commands before committing.
+
+Useful quick checks:
+
+```bash
+git status --short
+git diff -- .deuk-agent/tickets/INDEX.json
+git diff -- .deuk-agent/tickets/INDEX.archive.*.json
+```

package/docs/principles.ko.md

@@ -0,0 +1,68 @@
+# 원칙 (Principles)
+
+이 원칙들은 **DeukAgentRules**가 추구하는 "AI 엔지니어링 오케스트레이션 프로토콜"의 설계를 규정합니다.
+
+## 1. Zero-Copy Hub-Spoke 아키텍처 (SSoT)
+
+문서와 규칙 시스템은 단일 진실 공급원(Single Source of Truth)을 가져야 하며, 불필요한 규칙 복제를 피해야 합니다.
+
+- **Global Hub**: `AGENTS.md`는 모든 정본 규칙을 포함합니다.
+- **Local Hub**: `PROJECT_RULE.md`는 프로젝트에 특화된 규칙을 정의합니다.
+- **Spoke (Zero-Copy)**: IDE별 규칙 파일은 절대 경로 포인터 역할만 수행합니다.
+- **이유**: IDE마다 규칙이 복제되고 파편화되면 에이전트의 행동이 일관성을 잃고 예측 불가능해집니다.
+
+## 2. Zero-Legacy 정책
+
+더 이상 사용되지 않는 구조를 물리적으로 제거하여 저장소의 청결을 유지합니다.
+
+- **이유**: 레거시 `.cursorrules`나 스테일한 서브모듈 스텁은 에이전트를 혼란스럽게 하고 컨텍스트 윈도우를 낭비합니다.
+- **메커니즘**: `init` 실행 시 디프리케이션 마커와 빈 스텁을 무조건적으로 청소합니다.
+
+## 3. Kind Src (소스 주권)
+
+배포된 바이너리보다 로컬 개발 소스를 우선시합니다.
+
+- **이유**: npm 등에 배포된 패키지는 로컬의 최신 규칙 업데이트를 즉시 반영하지 못할 때가 많습니다.
+- **메커니즘**: Global CLI Proxy는 로컬에 `scripts/cli.mjs`가 존재할 경우 `npx` 명령을 해당 소스로 자동 위임합니다.
+
+## 4. Smart Backup (사용자 규칙 보호)
+
+시스템 생성 파일의 노이즈는 제거하되, 사람이 작성한 소중한 콘텐츠는 존중합니다.
+
+- **이유**: 사용자가 생성된 파일 하단에 직접 커스텀 룰을 추가하는 경우가 많습니다.
+- **메커니즘**: 순수 시스템 블록만 포함된 파일만 삭제하며, 그 외의 경우에는 `*.bak`으로 백업을 생성합니다.
+
+## 5. 엄격한 Phase 기반 워크플로우 (TDW)
+
+에이전트의 실행은 반드시 티켓과 Phase에 의해 제한되어야 합니다.
+
+- **이유**: 경계가 없는 AI 에이전트는 불필요한 파일을 탐색하며 토큰을 낭비하고 범위를 벗어난 수정을 시도합니다.
+- **메커니즘**: Phase 1에서 티켓을 발행하거나 기존 티켓을 선택하고 APC(Agent Permission Contract)를 채웁니다. 계획은 메인 티켓의 compact plan에만 둡니다. 진행 가능한 티켓이 없을 때는 후속 티켓을 만들기 전에 최근 git history를 분석합니다. 티켓은 스코프, 계약, 라이프사이클 체크, 검증 결과를 맡고, 계획 문구에는 진행 체크박스, 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 두지 않습니다.
+
+## 6. 변조 전 설계 (Plan Before Mutation)
+
+상태 변화가 일어나기 전에 설계가 명시적으로 선행되어야 합니다.
+
+- **이유**: 실제 코드나 설정 파일이 수정되기 전에 의도와 범위가 기록되어야 합니다. 티켓/계획 문서 자체는 기록물이며, 중복 티켓을 만들기 위한 승인 장벽이 아닙니다.
+- **메커니즘**: 코드를 작성하기 전 티켓의 APC 블록(`[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`)을 채웁니다. APC는 경계와 계약만 담습니다. 진단이나 접근 선택의 근거는 메인 티켓의 compact plan에 두고, 실행 기록의 목적지로 쓰지 않습니다.
+
+## 7. RAG를 보완하는 문서화
+
+안정적인 원칙과 동적인 지식은 함께 작동해야 합니다.
+
+- **Docs**: 안정적인 운영 모델과 가정들을 설명합니다.
+- **RAG (DeukAgentContext)**: 엔지니어링 메모리와 과거의 결정사항들을 온라인 MCP 계층을 통해서만 동기화합니다.
+- **이유**: 로컬 파일이 진실의 원천이고, RAG는 보조 기억이며, archive가 장기 이력을 보존해야 활성 context가 꼬이지 않습니다.
+
+## 8. 아카이브 보존
+
+아카이브는 선택 사항이 아니라 필수 생명주기 층입니다.
+
+- **이유**: 살아 있는 context는 작고 최신이어야 하며, 완료된 작업은 archive/knowledge로 옮겨야 활성 컨텍스트가 오염되지 않습니다.
+- **메커니즘**: ticket archive와 지식 증류를 통해 완료된 작업을 active loop에서 분리하고, 결과물을 장기 참조 자료로 유지합니다.
+
+## 9. 한/영 정합성 (Bilingual Parity)
+
+한국어와 영어 문서는 단일 모델의 거울 쌍이어야 합니다.
+
+- **이유**: 엔지니어링 팀은 다국어 환경인 경우가 많습니다. 문서 간 내용이 어긋나면 워크플로우 파편화가 발생합니다.

package/docs/principles.md

@@ -0,0 +1,68 @@
+# Principles
+
+These principles define the philosophy behind **DeukAgentRules** as an AI Engineering Orchestration Protocol.
+
+## 1. Zero-Copy Hub-Spoke Architecture (SSoT)
+
+The documentation and rule system must have a single source of truth without unnecessary duplication.
+
+- **Global Hub**: `AGENTS.md` contains all canonical rules.
+- **Local Hub**: `PROJECT_RULE.md` defines project-specific rules.
+- **Spoke (Zero-Copy)**: IDE-specific files act purely as absolute path pointers.
+- **Why**: Duplicated and mismatched rules across IDEs create agent drift and unpredictable behavior.
+
+## 2. Zero-Legacy Policy
+
+Maintain repository cleanliness by physically purging obsolete structures.
+
+- **Why**: Legacy `.cursorrules` or stale submodule stubs confuse agents and bloat the context window.
+- **Mechanism**: Unconditional cleanup of deprecated markers and empty stubs during `init`.
+
+## 3. Kind Src (Source Sovereignty)
+
+Prioritize local development source over distributed binaries.
+
+- **Why**: Distributed packages (npm) often lag behind local rule updates.
+- **Mechanism**: The Global CLI Proxy ensures that `npx` always routes to the local `scripts/cli.mjs` if present.
+
+## 4. Smart Backup (Custom Rule Protection)
+
+Respect human-authored content while cleaning system-generated noise.
+
+- **Why**: Users often add valuable custom rules to generated files.
+- **Mechanism**: Files are only deleted if they contain pure system blocks. Anything else is backed up as `*.bak`.
+
+## 5. Strict Phase-Driven Workflow (TDW)
+
+Execution must be strictly bounded by a Ticket and its Phase.
+
+- **Why**: AI agents wander without boundaries. Explicit scope locking reduces token usage and prevents scope-creep.
+- **Mechanism**: Phase 1 issues or selects a ticket and fills the Agent Permission Contract (APC). Keep all planning in the main ticket's compact plan. When no active/open ticket exists, the agent inspects recent git history before creating a follow-up ticket. The ticket owns scope, contract, lifecycle checks, and verification outcomes; planning text must not contain progress checkboxes, execution logs, command transcripts, completion summaries, or verification results.
+
+## 6. Plan Before Mutation
+
+Design must be explicit before state changes occur.
+
+- **Why**: Intent and scope should be recorded before code or config files are modified. Ticket and plan documents are records, not a reason to create duplicate tickets.
+- **Mechanism**: Before writing code, the ticket APC blocks (`[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`) must be filled. APC records boundary and contract only. The reasoning behind diagnosis and chosen approach stays in the main ticket's compact plan and is not a destination for execution records.
+
+## 7. Documentation Complements RAG
+
+Stable principles and dynamic knowledge must work together.
+
+- **Docs**: Explain the stable model and operating assumptions.
+- **RAG (DeukAgentContext)**: Synchronizes engineering memory and past decisions through the online MCP layer only.
+- **Why**: Local files stay the source of truth, RAG stays advisory, and archive preserves durable history without mixing live state into the memory layer.
+
+## 8. Archive Preservation
+
+Archive is a required lifecycle layer, not an optional afterthought.
+
+- **Why**: Live context should stay small and current, while completed work must be moved into archive/knowledge so the history remains searchable without polluting active context.
+- **Mechanism**: Use ticket archive and distillation to move finished work out of the active loop, then treat the archived result as durable reference material.
+
+## 9. Bilingual Parity
+
+English and Korean documentation are mirrors of a single model.
+
+- **Why**: Engineering teams are often bilingual. Mismatched docs lead to workflow fragmentation.

package/docs/usage-guide.ko.md

@@ -0,0 +1,139 @@
+# DeukAgentRules 실전 사용 가이드 (Practical Usage Guide)
+
+이 가이드는 DeukAgentRules를 실제 프로젝트에 배포하고 에이전트와 함께 효율적으로 사용하는 방법을 단계별로 설명합니다.
+
+---
+
+## 1. 프로젝트 초기화 (Deployment)
+
+새로운 프로젝트나 기존 프로젝트에 DeukAgentRules를 적용하려면 다음 단계를 따르세요.
+
+### 1단계: 글로벌 설치
+`npx` 캐시 문제를 피하고 어디서든 명령어를 사용할 수 있도록 글로벌 설치를 권장합니다.
+```bash
+npm install -g deuk-agent-rule
+```
+
+### 2단계: 워크스페이스 초기화
+프로젝트 루트 디렉토리에서 초기화 명령을 실행합니다.
+```bash
+deuk-agent-rule init
+```
+이 명령은 다음 파일들을 생성/업데이트합니다:
+- `PROJECT_RULE.md`: 현재 프로젝트의 고유 규칙 (전역 `AGENTS.md`를 오버라이드).
+- `.deuk-agent/`: 티켓, 템플릿, 설정이 저장되는 디렉토리.
+- `.cursor/rules/deuk-agent.mdc`, `GEMINI.md` 등: 각 에이전트 환경에 맞는 얇은 포인터 파일.
+
+---
+
+## 2. 에이전트와 협업하기 (Daily Workflow)
+
+에이전트에게 작업을 시킬 때는 항상 **티켓**을 기반으로 소통하세요.
+
+### 1단계: 티켓 생성 (Phase 1: Ticket + Plan)
+에이전트에게 다음과 같이 요청하여 작업을 시작합니다.
+> 💬 "새로운 기능을 위한 티켓을 만들어줘. 주제는 'user-auth-impl'이야."
+
+에이전트는 내부적으로 다음 명령을 실행합니다:
+```bash
+deuk-agent-rule ticket create --topic user-auth-impl --evidence "기존 auth 로직 분석 완료..."
+```
+이미 작성된 Phase 1 본문이 있다면 `--plan-body` 옵션으로 티켓 내부에 바로 넣을 수도 있습니다.
+
+반복 생성과 자리표시자만 남는 루프를 막으려면, 아래처럼 **한 번에 끝나는 형태**를 기본으로 쓰는 편이 좋습니다.
+
+```bash
+npx deuk-agent-rule ticket create \
+  --topic user-auth-impl \
+  --summary "기존 auth 로직과 충돌하지 않는 신규 인증 흐름 정리" \
+  --plan-body "$(cat <<'EOF'
+# User auth implementation
+## Agent Permission Contract (APC)
+### [BOUNDARY]
+- ...
+### [CONTRACT]
+- ...
+### [PATCH PLAN]
+- ...
+## Compact Plan
+- Finding: ...
+- Approach: ...
+- Verification: ...
+## Problem Analysis
+- ...
+## Source Observations
+- ...
+## Cause Hypotheses
+- ...
+## Improvement Direction
+- ...
+## Audit Evidence
+- ...
+EOF
+)" \
+  --require-filled \
+  --non-interactive
+```
+
+`--require-filled`를 붙이면 APC와 compact plan이 비어 있을 때 생성이 실패하므로, 에이전트가 placeholder를 고치느라 여러 번 반복하는 상황을 줄일 수 있습니다.
+
+기존 작업을 이어받으려는데 `ticket next`가 진행 가능한 티켓을 찾지 못하면, 에이전트는 새 티켓을 즉시 만들지 않고 최근 git history를 먼저 분석해 실제 후속 작업 후보를 복원합니다. 새 티켓은 그 분석 근거를 메인 티켓의 compact plan에 기록한 뒤 생성합니다.
+
+### 2단계: APC(Agent Permission Contract) 기록
+생성된 티켓은 기본적으로 **Phase 1 (Ticket + Plan)** 상태입니다. 에이전트는 코드를 수정하기 전에 티켓 내의 APC 블록(`[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`)을 채워야 합니다.
+
+티켓은 스코프, 제약, APC 계약, 라이프사이클 체크, 검증 결과를 맡습니다. 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 계획 문구와 섞지 않습니다.
+
+사용자가 실행을 명확히 요청했고 Phase 1 기록이 완성되어 있으면, 에이전트가 다음 명령으로 Phase 승급을 시도합니다:
+```bash
+deuk-agent-rule ticket move --topic user-auth-impl
+```
+만약 APC나 compact plan이 비어있거나 불완전하다면, 에이전트는 코딩 전에 이를 먼저 채웁니다.
+
+이슈/회귀/정책 위반을 제기한 경우에는 티켓 생성 직후 바로 실행하지 않습니다. 에이전트는 Phase 1에 원인 가설, 범위, APC, 패치 계획을 채운 뒤 멈추고 사용자의 검토 승인을 기다립니다. 원래 요청에 "수정", "해결"이 포함되어 있어도 티켓 계획을 본 뒤의 승인으로 보지 않습니다.
+
+### 3단계: 작업 실행 (Phase 2: Execute)
+티켓이 **Phase 2 (Execute)** 로 승급되면, 에이전트는 제한된 경계 내에서 코드를 수정하고 단위 테스트 등 검증 작업을 수행합니다.
+
+### 4단계: 작업 완료 및 아카이빙
+작업이 끝나면 에이전트에게 리포트 작성과 티켓 보관을 요청하세요.
+> 💬 "작업 완료했어. 리포트 작성하고 티켓 아카이브해줘."
+
+이때 아카이브 작업 중 **Zero-Token 지식 증류(Knowledge Distillation)**가 동작하여 불필요한 컨텍스트 토큰 소모를 줄이도록 핵심 정보만 압축되어 저장됩니다.
+
+### 5단계: 티켓 파일 깃 관리
+티켓 파일도 깃 기록의 일부이지만, 소스 코드처럼 무심코 다루면 active/archive 상태가 쉽게 꼬입니다.
+
+- `ticket create`, `ticket move`, `ticket close`, `ticket archive`로 바뀐 `.deuk-agent/tickets/INDEX*.json`은 함께 커밋합니다. 티켓 본문만 커밋하고 index를 빼면 다음 작업에서 상태가 맞지 않을 수 있습니다.
+- `.deuk-agent/tickets/**/*.md`는 CLI가 만든 결과만 따라갑니다. 티켓 생성이 실패한 뒤 파일을 손으로 만들거나 고치지 않습니다.
+- 작업 중 티켓 본문을 다듬는 것은 괜찮지만, 상태를 바꿀 때는 frontmatter를 직접 고치지 말고 반드시 CLI를 사용합니다.
+- `.deuk-agent/telemetry.jsonl`은 보통 실행 로그에 가깝기 때문에, 저장소 정책상 꼭 추적하는 경우가 아니라면 커밋 목록에 넣지 않는 편이 안전합니다.
+- 작업을 끝냈다면 `ticket archive`까지 마친 뒤 커밋하는 편이 좋습니다. archive는 티켓 파일 위치와 archive index를 함께 정리하므로, 중간에 손으로 옮기면 기록 흐름이 흐려집니다.
+- 여러 작업을 한 커밋에 섞지 말고, 가능하면 "코드 변경 + 해당 티켓 lifecycle 변경" 묶음으로 나눕니다.
+
+빠르게 확인할 때는 아래 정도를 습관처럼 보면 좋습니다.
+
+```bash
+git status --short
+git diff -- .deuk-agent/tickets/INDEX.json
+git diff -- .deuk-agent/tickets/INDEX.archive.*.json
+```
+
+티켓 관련 변경이 보일 때는 "이 변경이 CLI lifecycle의 결과인가?"를 먼저 확인하세요. 아니라면 손으로 고치기보다 `ticket status`, `ticket list`, `ticket archive` 같은 명령으로 상태를 다시 맞추는 편이 안전합니다.
+
+---
+
+## 3. 에이전트 프롬프트 가이드 (Agent Prompting)
+
+에이전트가 DeukAgentRules 프로토콜을 엄격히 준수하도록 하려면 프로젝트 시작 시 다음과 같은 **페르소나 주입(Persona Injection)**이 도움이 됩니다.
+
+> **에이전트 지침 예시:**
+> "너는 DeukAgentRules 프로토콜을 준수하는 시니어 엔지니어다. 모든 코드 수정 전에는 반드시 `ticket create` 또는 기존 티켓 선택을 통해 Phase 1 기록을 만들고, 티켓에는 APC 경계/계약과 compact plan을 담는다. 이슈/회귀/정책 위반 보고는 티켓 생성 후 Phase 1 계획을 사용자에게 검토받고, 승인 후에만 Phase 2로 승급한다. 작업이 완료되면 검증 결과를 티켓 또는 리포트에 기록하고 티켓을 `archive`해라. 규칙 파일인 `PROJECT_RULE.md`와 포인터가 가리키는 `AGENTS.md`를 항상 최우선으로 참조하라."
+
+---
+
+## 4. 팁 및 모범 사례
+
+- **No Ticket, No Code**: 티켓 없이 코드를 수정하는 것은 금지됩니다. 작은 수정이라도 티켓을 생성하여 이력을 남기세요.
+- **RAG 활용**: `mcp_deukcontext_search_*` 도구를 사용하여 과거 티켓이나 구현 사례를 검색하면 환각을 줄일 수 있습니다.
+- **주기적 동기화**: 프로젝트 규칙이 변경되었다면 `deuk-agent-rule init`을 다시 실행하여 모든 에이전트 포인터를 갱신하세요.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deuk-agent-rule",
-  "version": "3.3.2",
+  "version": "3.3.3",
   "description": "AI coding agent guardrails for every repo: ticketed scope, verification, and shared AGENTS.md workflows.",
   "keywords": [
     "agents-md",
@@ -28,6 +28,14 @@
   "files": [
     "LICENSE",
     "bin/**/*",
+    "docs/architecture.md",
+    "docs/architecture.ko.md",
+    "docs/how-it-works.md",
+    "docs/how-it-works.ko.md",
+    "docs/principles.md",
+    "docs/principles.ko.md",
+    "docs/usage-guide.ko.md",
+    "docs/assets/**/*",
     "templates/**/*",
     "scripts/cli.mjs",
     "scripts/cli-args.mjs",