deuk-agent-rule 2.5.14 → 3.3.3

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,7 +1,7 @@
 {
   "name": "deuk-agent-rule",
-  "version": "2.5.14",
-  "description": "DeukAgentRules: generic AGENTS.md + .cursor rule templates with init/merge CLI (npm name: deuk-agent-rule).",
+  "version": "3.3.3",
+  "description": "AI coding agent guardrails for every repo: ticketed scope, verification, and shared AGENTS.md workflows.",
   "keywords": [
     "agents-md",
     "cursor-rules",
@@ -11,6 +11,8 @@
     "windsurf",
     "jetbrains",
     "ticket",
+    "ai-guardrails",
+    "agent-guardrails",
     "deuk-family",
     "deukpack-ecosystem"
   ],
@@ -25,21 +27,49 @@
   "homepage": "https://github.com/joygram/DeukAgentRules#readme",
   "files": [
     "LICENSE",
-    "bundle/**/*",
-    "scripts/**/*.mjs",
+    "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",
+    "scripts/cli-init-commands.mjs",
+    "scripts/cli-init-logic.mjs",
+    "scripts/cli-prompts.mjs",
+    "scripts/cli-rule-compiler.mjs",
+    "scripts/cli-skill-commands.mjs",
+    "scripts/cli-telemetry-commands.mjs",
+    "scripts/cli-ticket-commands.mjs",
+    "scripts/cli-ticket-index.mjs",
+    "scripts/cli-ticket-migration.mjs",
+    "scripts/cli-ticket-parser.mjs",
+    "scripts/cli-utils.mjs",
+    "scripts/lint-md.mjs",
+    "scripts/lint-rules.mjs",
+    "scripts/merge-logic.mjs",
+    "scripts/plan-parser.mjs",
     "README.md",
     "README.ko.md",
     "CHANGELOG.md",
     "CHANGELOG.ko.md"
   ],
   "scripts": {
-    "sync": "node scripts/sync-bundle.mjs",
-    "prepack": "node scripts/sync-bundle.mjs"
+    "lint:md": "node scripts/lint-md.mjs",
+    "test": "node --test scripts/tests/*.test.mjs"
   },
   "engines": {
     "node": ">=18"
   },
-  "bin": {},
+  "bin": {
+    "deuk-agent-rule": "./bin/deuk-agent-rule.js",
+    "deukagentrule": "./bin/deuk-agent-rule.js"
+  },
   "dependencies": {
     "ejs": "^5.0.2",
     "yaml": "^2.8.3"

package/scripts/cli-args.mjs

@@ -5,15 +5,16 @@ export function parseTicketArgs(argv) {
     if (a === "--cwd") out.cwd = argv[++i];
     else if (a === "--dry-run") out.dryRun = true;
     else if (a === "--non-interactive") out.nonInteractive = true;
-    else if (a === "--topic") out.topic = argv[++i];
+    else if (a === "--topic" || a === "--id") out.topic = argv[++i];
     else if (a === "--group") out.group = argv[++i];
     else if (a === "--project") out.project = argv[++i];
     else if (a === "--content") out.content = argv[++i];
     else if (a === "--from") out.from = argv[++i];
+    else if (a === "--plan-body") out.planBody = argv[++i];
     else if (a === "--ref") out.ref = argv[++i];
     else if (a === "--limit") out.limit = Number(argv[++i]);
     else if (a === "--submodule") out.submodule = argv[++i];
-    else if (a === "--latest") out.latest = true;
+    else if (a === "--latest" || a === "-l") out.latest = true;
     else if (a === "--path-only") out.pathOnly = true;
     else if (a === "--print-content") out.printContent = true;
     else if (a === "--all") out.all = true;
@@ -25,6 +26,22 @@ export function parseTicketArgs(argv) {
     else if (a === "--remote") out.remote = argv[++i];
     else if (a === "--sync") out.sync = true;
     else if (a === "--no-sync") out.sync = false;
+    else if (a === "--chain") out.chain = true;
+    else if (a === "--render") out.render = true;
+    else if (a === "--docs-language") out.docsLanguage = argv[++i];
+    else if (a === "--evidence") out.evidence = argv[++i];
+    else if (a === "--skip-phase0") out.skipPhase0 = true;
+    else if (a === "--summary") out.summary = argv[++i];
+    else if (a === "--tags") out.tags = argv[++i];
+    else if (a === "--phase") out.phase = Number(argv[++i]);
+    else if (a === "--next") out.next = true;
+    else if (a === "--handoff") out.handoff = true;
+    else if (a === "--reason") out.reason = argv[++i];
+    else if (a === "--claim") out.claim = argv[++i];
+    else if (a === "--require-filled") out.requireFilled = true;
+    else if (a === "--allow-placeholder") out.allowPlaceholder = true;
+    else if (a === "--compact") out.compact = true;
+    else if (a === "--status-detail") out.statusDetail = true;
   }
   return out;
 }
@@ -43,14 +60,81 @@ export function parseArgs(argv) {
     else if (a === "--marker-begin") out.markerBegin = argv[++i];
     else if (a === "--marker-end") out.markerEnd = argv[++i];
     else if (a === "--agents") out.agents = argv[++i];
-    else if (a === "--rules") out.rules = argv[++i];
     else if (a === "--cursorrules") out.cursorrules = argv[++i];
     else if (a === "--append-if-no-markers") out.appendIfNoMarkers = true;
+    else if (a === "--workflow") out.workflowMode = argv[++i];
+    else if (a === "--approval") out.approval = argv[++i];
     else if (a === "--json") out.json = true;
     else if (a === "--remote") out.remote = argv[++i];
     else if (a === "--sync") out.sync = true;
     else if (a === "--no-sync") out.sync = false;
+    else if (a === "--docs-language") out.docsLanguage = argv[++i];
+    else if (a === "--compact") out.compact = true;
     else if (a === "-h" || a === "--help") out.help = true;
   }
   return out;
 }
+
+export function parseSkillArgs(argv) {
+  const out = { cwd: process.cwd(), dryRun: false, nonInteractive: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--cwd") out.cwd = argv[++i];
+    else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--non-interactive") out.nonInteractive = true;
+    else if (a === "--skill" || a === "--id") out.skill = argv[++i];
+    else if (a === "--platform") out.platform = argv[++i];
+    else if (a === "--json") out.json = true;
+  }
+  return out;
+}
+export function parseTelemetryArgs(argv) {
+  const out = {
+    cwd: process.cwd(),
+    tokens: 0,
+    tdw: 0,
+    model: "",
+    client: "",
+    ticket: "",
+    action: "",
+    file: "",
+    remote: "",
+    source: "",
+    kind: "",
+    event: "",
+    occurredAt: "",
+    phase: "",
+    status: "",
+    ragResult: "",
+    localFallback: false,
+    knowledgeAction: "",
+    tokenQuality: "",
+    savedTokens: 0,
+    json: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--cwd") out.cwd = argv[++i];
+    else if (a === "--tokens") out.tokens = Number(argv[++i]);
+    else if (a === "--tdw") out.tdw = Number(argv[++i]);
+    else if (a === "--model") out.model = argv[++i];
+    else if (a === "--client") out.client = argv[++i];
+    else if (a === "--ticket") out.ticket = argv[++i];
+    else if (a === "--action") out.action = argv[++i];
+    else if (a === "--file") out.file = argv[++i];
+    else if (a === "--remote") out.remote = argv[++i];
+    else if (a === "--source") out.source = argv[++i];
+    else if (a === "--kind") out.kind = argv[++i];
+    else if (a === "--event") out.event = argv[++i];
+    else if (a === "--occurred-at") out.occurredAt = argv[++i];
+    else if (a === "--phase") out.phase = Number(argv[++i]);
+    else if (a === "--status") out.status = argv[++i];
+    else if (a === "--rag-result") out.ragResult = argv[++i];
+    else if (a === "--local-fallback") out.localFallback = true;
+    else if (a === "--knowledge-action") out.knowledgeAction = argv[++i];
+    else if (a === "--token-quality") out.tokenQuality = argv[++i];
+    else if (a === "--saved-tokens") out.savedTokens = Number(argv[++i]);
+    else if (a === "--json") out.json = true;
+  }
+  return out;
+}