deuk-agent-rule 3.3.3 → 4.0.19

package/LICENSE

@@ -1,184 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship made available under
-      the License, as indicated by a copyright notice that is included in
-      or attached to the work (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean, as submitted to the Licensor for inclusion
-      in the Work by the copyright owner or by an individual or Legal Entity
-      authorized to submit on behalf of the copyright owner. For the purposes
-      of this definition, "submitted" means any form of electronic, verbal,
-      or written communication sent to the Licensor or its representatives,
-      including but not limited to communication on electronic mailing lists,
-      source code control systems, and issue tracking systems that are managed
-      by, or on behalf of, the Licensor for the purpose of submitting and
-      discussing modifications to the Work, but excluding communication that
-      is conspicuously marked or designated in writing by the copyright owner
-      as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any Legal Entity on behalf of
-      whom a Contribution has been received by the Licensor and included
-      within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by the combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a cross-claim
-      or counterclaim in a lawsuit) alleging that the Work or any other
-      Contribution embodied in the Work constitutes patent or contributory
-      patent infringement, then any patent rights granted to You under
-      this License for that Work shall terminate as of the date such
-      litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or Derivative
-          Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, You must include a readable copy of the
-          attribution notices contained within such NOTICE file, in
-          at least one of the following places: within a NOTICE text
-          file distributed as part of the Derivative Works; within
-          the Source form or documentation, if provided along with the
-          Derivative Works; or, within a display generated by the
-          Derivative Works, if and wherever such third-party notices
-          normally appear. The contents of the NOTICE file are for
-          informational purposes only and do not modify the License.
-          You may add Your own attribution notices within Derivative
-          Works that You distribute, alongside or as an addendum to
-          the NOTICE text from the Work, provided that such additional
-          attribution notices cannot be construed as modifying the License.
-
-      You may add Your own license statement for Your modifications and
-      may provide additional grant of rights to use, copy, modify, merge,
-      publish, distribute, sublicense, and/or sell copies of the Work,
-      and to permit persons to whom the Work is furnished to do so,
-      subject to the following conditions:
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any conditions of TITLE,
-      NONINFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
-      PURPOSE. You are solely responsible for determining the
-      appropriateness of using or reproducing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or exemplary damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or all other
-      commercial damages or losses), even if such Contributor has been
-      advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may offer such
-      conditions only on Your own behalf and on Your sole responsibility,
-      not on behalf of any other Contributor, and only if You agree to
-      indemnify, defend, and hold each Contributor harmless for any
-      liability incurred by, or claims asserted against, such Contributor
-      by reason of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   Copyright 2025 Deukware and contributors
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

package/README.ko.md

@@ -1,187 +0,0 @@
-<div align="center">
-  <br />
-  <img src="docs/assets/architecture-v3.png" width="800" alt="DeukAgentRules Architecture" />
-  <br />
-  <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>
-  </p>
-  <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>
-
----
-
-**DeukAgentRules**는 AI 코딩 에이전트가 티켓, 범위 계약, 검증 기록, 프로젝트 기억을 공유된 방식으로 따라가게 만드는 레포 단위 워크플로우입니다.
-
-단순한 프롬프트 모음에 머물지 않습니다. **Hub-Spoke 아키텍처**와 **티켓 기반 실행 모델**을 통해 `AGENTS.md`, Copilot instructions, Cursor rules, Claude skills 같은 에이전트 지침 표면을 하나의 레포 워크플로우로 묶습니다.
-
-티켓 관리는 `.deuk-agent/` 아래에서 이뤄지며, 진행 중인 작업은 `.deuk-agent/tickets/`에, 관련 문서와 계획, 아카이브 정보도 그 주변 구조에 함께 쌓입니다.
-
-> **현재 배포 기준:**
-> v3.3.3은 에이전트 기반 리포지토리에 배포해 사용할 수 있는 상태입니다. 현재는 **OpenAI Codex**와 **GitHub Copilot** 환경에서 가장 안정적으로 동작합니다. Cursor, Windsurf, Claude Code, MCP도 포인터 구조로 지원하지만, 워크스페이스별 검증을 권장합니다. MCP 서버 등록은 `init`에 딸려 들어가지 않고 별도로 설정합니다.
-
-> **아키텍처 기반:**
-> 거대하고 무거운 레거시 `.cursorrules` 방식을 공식적으로 폐기했습니다. v3.0은 `AGENTS.md`를 단일 진실 공급원으로 사용하는 **Hub-Spoke 모델**을 도입하여, IDE별 규칙은 얇은 진입점 포인터 역할만 수행합니다.
-
-### 🗺️ 핵심 기능 및 아키텍처 (Main Features)
-
-DeukAgentRules는 AI 에이전트가 코드를 분석하고 작성하는 흐름을 안정적으로 이끄는 **4대 핵심 기능**을 제공합니다.
-
-1. **Zero-Copy Hub-Spoke 아키텍처**
-   - **Hub**: 단일 진실 공급원인 `AGENTS.md` (글로벌 룰)
-   - **Spoke**: `PROJECT_RULE.md` 등 워크스페이스별 로컬 규칙
-   - **효과**: IDE별(Cursor, Copilot, Windsurf) 설정 파일 중복을 제거하고, 에이전트가 오직 하나의 규약만 바라보게 하여 지시 사항의 충돌과 환각을 원천 차단합니다.
-
-2. **티켓 주도 워크플로우 (TDW: Ticket-Driven Workflow)**
-   - 계획(Plan) → 실행(Execute) → 검증(Verify) → 보관(Archive)의 분명한 라이프사이클로 작업을 이끕니다.
-   - 활성화된 티켓(`ACTIVE_TICKET.md`)을 중심으로 변경을 연결해 범위와 진행 상태가 계속 보이게 합니다.
-
-3. **플랫폼 공존 및 모드 인지형 게이트 (Mode-Aware Workflow Gate)**
-   - 에이전트의 현재 모드(Plan Mode vs. Execute Mode)를 인지하여, Plan Mode에서는 분석과 구현 계획서(Artifacts) 작성에 집중하도록 APC를 적용합니다.
-   - MCP(Model Context Protocol) Soft Gate와 연동되어 현재 티켓 컨텍스트에 맞는 변경 흐름을 유지합니다.
-
-4. **지식 증류 및 Zero-Legacy (Knowledge Distillation)**
-   - 완료된 작업은 `reports/`로 아카이빙되며, 이 과정에서 **Zero-Token 지식 증류** 기술이 적용되어 핵심 히스토리만 벡터 DB(DeukAgentContext)로 전달됩니다.
-   - 불필요한 과거 로그나 사용되지 않는 `.cursorrules` 스텁을 자동으로 청소하여 컨텍스트 윈도우 낭비를 막습니다.
-
-### 지침 파일만으로 부족한 이유
-
-이미 AI 코딩 에이전트 생태계에는 `AGENTS.md`, GitHub Copilot instructions, Cursor rules, Claude skills, 여러 에이전트 실행 도구, 일반 LLM 가드레일이 있습니다. DeukAgentRules는 이들과 경쟁하기보다 그 위에 **티켓 기반 레포 워크플로우**를 얹습니다.
-
-| 비슷한 접근 | 도움이 되는 부분 | DeukAgentRules가 더하는 것 |
-|---|---|---|
-| `AGENTS.md` 공개 형식 | 코딩 에이전트가 읽을 공통 지침 파일 | 티켓 생명주기, Phase Gate, 검증, 아카이브 가능한 기억 |
-| Copilot instructions / Cursor rules / Claude memory | 도구별 맞춤 지침 | 여러 에이전트가 공유하는 레포 소유 워크플로우 |
-| Claude/Copilot custom agent와 skill | 재사용 가능한 작업 playbook | skill이 워크플로우를 대체하지 않고 티켓 실행으로 들어가게 함 |
-| 에이전트 실행기와 harness | 여러 코딩 에이전트 실행 | 어떤 에이전트를 쓰든 레포 안에서 생명주기를 통제 |
-| 일반 LLM/MCP 가드레일 | 런타임 정책 검사 | 작업 지시서, 범위 계약, 깃에 남는 기록, 완료 근거 |
-
-DeukAgentRules는 AI 코딩 작업을 팀이 이해하고 이어받기 쉬운 흐름으로 만들고 싶을 때 특히 잘 맞습니다. 여러 파일에 걸친 변경, 검증, 기록, 다음 작업 연결이 자연스럽게 이어지도록 돕는 데 초점을 둡니다.
-
-### Karpathy식 skill과 같이 쓰면 좋은 점
-
-Karpathy식 skill은 한 작업 안에서 에이전트의 행동을 더 좋게 만드는 데 강합니다. DeukAgentRules는 그 작업을 레포 차원에서 티켓화하고, 범위를 맞추고, 검증하고, 다시 찾을 수 있게 남기는 데 강합니다.
-
-둘을 함께 쓰면 skill은 작업 수행 품질을 끌어올리고, DeukAgentRules는 그 결과를 팀 워크플로우에 연결합니다. 앞단에서는 행동 playbook이 작동하고, 뒷단에서는 티켓 생명주기와 DeukAgentContext 기억 계층이 남습니다.
-
-### 다음 개선 방향
-
-다음 단계는 이 워크플로우를 더 잘 보이고 더 쉽게 도입하게 만드는 것입니다. 첫 실행 점검을 더 명확히 하고, CLI/RAG 결과에 짧은 재각인 신호를 붙이며, README/npm 포지셔닝을 강화하고, active ticket, phase, open ticket count, DeukAgentContext memory status를 보여주는 companion 표면을 준비하는 방향입니다. 목표는 팀이 쓰는 코딩 에이전트를 바꾸지 않고도 같은 작업 규율을 자연스럽게 얻는 것입니다.
-
-### 📚 상세 문서
-| 문서 | 용도 |
-|---|---|
-| [docs/usage-guide.ko.md](docs/usage-guide.ko.md) | **[추천]** 실전 배포 및 단계별 사용 가이드 |
-| [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, 소스 주권 |
-| **English Docs** | [README.md](README.md) · [docs/architecture.md](docs/architecture.md) |
-
----
-
-## 🚀 빠른 시작 (Quick Start)
-
-가장 빠르게 DeukAgentRules를 프로젝트에 도입하는 방법입니다.
-
-```bash
-# 1. 글로벌 설치
-npm install -g deuk-agent-rule
-
-# 2. 프로젝트 초기화 (AGENTS.md 및 설정 생성)
-deuk-agent-rule init
-
-# 3. 첫 번째 작업 티켓 생성
-deuk-agent-rule ticket create --topic my-first-task
-```
-
-자세한 실전 활용법은 **[실전 사용 가이드](docs/usage-guide.ko.md)**를 참조하세요.
-
-## 🛠️ 설치 및 설정
-
-### 1. 글로벌 설치 (일반 사용자)
-\`npx\` 캐시 문제와 "로컬 트랩"을 방지하기 위해 글로벌 설치가 엄격히 권장됩니다.
-
-\`\`\`bash
-npm install -g deuk-agent-rule
-deuk-agent-rule init
-\`\`\`
-
-### 2. 로컬 소스 개발 (메인테이너/파워 유저)
-v3.0은 **Global CLI Proxy**를 도입했습니다. \`DeukAgentRules\` 워크스페이스 내부에서 개발 중이라면, 글로벌 명령이 자동으로 로컬 소스로 실행을 위임합니다.
-
-\`\`\`bash
-cd ~/workspace/DeukAgentRules
-sudo npm link
-deuk-agent-rule init  # 자동으로 로컬 scripts/cli.mjs로 라우팅됨
-\`\`\`
-
-Codex나 Copilot을 주로 사용한다면 이 구성이 일상 운영에 가장 적합합니다. 현재는 이 두 환경에서 Hub-Spoke와 티켓 기반 워크플로우가 가장 부드럽게 동작합니다.
-
----
-
-## 🎯 프로토콜 워크플로우
-
-워크플로우는 **티켓 기반 실행 계약(Ticket-Driven Execution Contract)**에 의해 통제됩니다.
-
-1. **스캐폴딩 (Scaffolding)**: `init` 명령어가 프로젝트의 성격을 파악하고 `.deuk-agent/templates/`와 `AGENTS.md` (혹은 `PROJECT_RULE.md` 포인터)를 자동 배치합니다.
-2. **티켓팅 (Plan Phase)**: `ticket create --topic feature-x` 명령어로 새로운 작업 지시서를 생성합니다. 이때 에이전트는 Plan Mode로 동작하며 코드를 수정할 수 없고 계획 수립에만 집중합니다.
-3. **실행 (Execute Phase)**: 사용자의 승인을 받은 후, 에이전트는 **타겟 서브모듈**에 고정되어 실질적인 코드 작성을 수행합니다. MCP Soft Gate가 인가되지 않은 파일의 수정을 감시합니다.
-4. **검증 (Verify Phase)**: 개발 작업 종료 전 사이드 이펙트 감사(Audit) 및 컨벤션(DC-DUP 등 아키텍처 규칙) 체크를 수행합니다.
-5. **아카이빙 (Archive Phase)**: 완료된 티켓은 Zero-Token 지식 증류를 거쳐 `reports/`로 이동하며, 이 데이터는 DeukAgentContext 벡터 데이터베이스에 저장되어 영구적인 **엔지니어링 메모리 엔진**으로 작동합니다.
-
----
-
-## ⚙️ CLI 주요 명령어
-
-자연어 프롬프트를 통해 AI 에이전트에게 직접 시키세요!
-
-| 명령어 | 설명 / 프롬프트 예시 |
-|--------|------|
-| \`deuk-agent-rule init\` | 규칙 허브와 스포크 포인터를 동기화합니다. <br>💬 *"프로젝트 규칙 초기화해줘"* |
-| \`deuk-agent-rule ticket create\` | 새로운 실행 계약(티켓)을 발행합니다. `--summary`와 `--plan-body`를 함께 넣어 1회 생성으로 Phase 1을 끝내는 것을 권장합니다. <br>💬 *"refactor-ui 티켓을 APC까지 채워서 만들어줘"* |
-| \`deuk-agent-rule ticket list\` | 활성화된 작업 지시서를 표시합니다. <br>💬 *"활성 티켓 목록 보여줘"* |
-| \`deuk-agent-rule ticket archive\` | 완료된 작업을 안전하게 보관합니다. <br>💬 *"068번 티켓 아카이브해줘"* |
-| \`deuk-agent-rule skill list\` | `safe-refactor`, `generated-file-guard`, `context-recall` 같은 first-party 얇은 skill을 보여줍니다. |
-| \`deuk-agent-rule skill add --skill safe-refactor\` | TDW/APC 권한 모델을 바꾸지 않고 로컬 skill registry에 skill을 설치합니다. |
-| \`deuk-agent-rule skill expose --platform claude\` | 설치된 skill을 플랫폼별 얇은 wrapper로 노출합니다. MVP 지원 플랫폼은 `claude`, `cursor`입니다. |
-| \`deuk-agent-rule skill lint\` | skill 파일이 중복 workflow 계약이나 generated 파일 직접 수정 지침을 담지 않았는지 검사합니다. |
-
-### 티켓 파일 깃 관리 원칙
-
-- `.deuk-agent/tickets/**/*.md`와 `INDEX*.json`은 CLI가 바꾼 결과만 반영합니다.
-- 티켓 본문만 커밋하고 index를 빼먹지 마세요. 다음 작업에서 상태가 맞지 않을 수 있습니다.
-- 생성이 실패한 뒤 티켓 파일을 손으로 만들거나 frontmatter로 상태를 바로 바꾸지 마세요.
-- `telemetry.jsonl`은 보통 실행 로그이므로 일반 코드 커밋에는 넣지 않는 편이 낫습니다.
-- 작업을 마쳤다면 가능하면 `ticket archive`까지 끝낸 뒤 커밋해 active/archive 흐름이 함께 남도록 하세요.
-
-자세한 사용 예시는 [docs/usage-guide.ko.md](docs/usage-guide.ko.md)를 참고하세요.
-
----
-
-## 관련 아이디어와 영감
-
-DeukAgentRules는 [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)처럼
-AI 코딩 에이전트가 잘못 가정하고, 과하게 구현하고, 요청 밖 코드를 수정하는 문제의식과 맞닿아 있습니다.
-
-다만 DeukAgentRules는 프롬프트 수준의 지침 파일을 넘어 티켓, Phase Gate,
-스코프 계약, 검증, 아카이브 가능한 엔지니어링 메모리까지 제공하는 레포 단위 워크플로우 계층입니다.
-
-first-party skill MVP는 이 경계를 명확히 유지합니다. skill은 반복 실패 패턴을 다루는 짧은
-`SKILL.md` playbook이고, workflow 권한의 단일 기준은 계속 `core-rules/AGENTS.md`입니다.
-`skill add`와 `skill expose`로 Claude/Cursor에 playbook을 노출하되, 전체 rule contract를 복사하지 않습니다.
-
-\`\`\`bash
-npx deuk-agent-rule init
-npx deuk-agent-rule skill list
-npx deuk-agent-rule skill add --skill safe-refactor
-npx deuk-agent-rule skill expose --platform claude
-\`\`\`
-
----
-
-### 🏷️ 검색 태그
-\`#AI-Orchestration\` \`#Agentic-Workflow\` \`#DeukFamily\` \`#Engineering-Intelligence\` \`#Zero-Legacy\` \`#High-Signal-Coding\` \`#AI-Protocol\` \`#CursorRules\` \`#CopilotInstructions\` \`#ClaudeCode\` \`#ClaudeMD\` \`#AgentsMD\` \`#AgentSkills\` \`#CodingAgent\` \`#AI-Guardrails\` \`#LLM-Control-Plane\`

package/docs/architecture.ko.md

@@ -1,34 +0,0 @@
-# 아키텍처 (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

@@ -1,33 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 작동 원리 (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

@@ -1,71 +0,0 @@
-# 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

@@ -1,68 +0,0 @@
-# 원칙 (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)
-
-한국어와 영어 문서는 단일 모델의 거울 쌍이어야 합니다.
-
-- **이유**: 엔지니어링 팀은 다국어 환경인 경우가 많습니다. 문서 간 내용이 어긋나면 워크플로우 파편화가 발생합니다.