deuk-agent-flow 4.0.19

package/core-rules/AGENTS.md

@@ -0,0 +1,153 @@
+---
+version: 65
+changelog: "v65: Collapse compact ticket-selection CLI output and running commentary surfaces to a single ticket-start line or silence."
+---
+
+# Agent Rules
+
+## Compact Kernel
+
+- Tools own detail. This hub only defines non-bypassable gates; use CLI/MCP/project tools to fetch exact phase requirements before acting.
+- No ticket, no writes: before file changes, select or create one active ticket, relay the CLI-provided ticket-start line in chat, reopen and review the durable ticket body, wait for explicit user approval, complete Phase 1 in that ticket, run `deuk-agent-flow ticket guard --topic <id> --ticket-started --ticket-reviewed --approval approved` successfully, and call `set_workflow_context(project, ticket_id, phase)`.
+- User requirements are ticket-first: every user request that implies investigation, change, verification, or judgment must first be represented in a ticket containing cause, analysis, and design/approach before work continues.
+- Existing-ticket close actions are not new-ticket triggers: when the user asks to commit, report, archive, or close work that is already inside the approved active ticket scope, treat it as that ticket's Phase 4 close action unless the user also adds new scope.
+- User approval or correction creates another ticket update loop: record the approval/correction in the ticket, re-check scope and plan, then continue only through `deuk-agent-flow ticket guard --ticket-started --ticket-reviewed --approval approved`.
+- Approval is mandatory for every ticket. A ticket may not progress without explicit user approval, regardless of urgency or convenience.
+- `Ticket start` exposure is not approval. Phrases such as "진행", "go ahead", or "continue" count only after the agent has shown the exact ticket link, scope, and planned change summary for the active ticket; otherwise treat them as a request for scope clarification and stop.
+- Approval review must treat `rank/priority` as a hard gate. If `rank/priority` is missing, the ticket is incomplete and approval must be withheld.
+- Do not create or expand tests unless the user explicitly asks for tests. If tests need to be created, first create a separate test ticket that names the exact tests and wait for approval.
+- Unapproved Phase 1 tickets must be discarded with `deuk-agent-flow ticket discard`; do not leave abandoned pending tickets as active work.
+- Reinforcement only counts when it is written into the durable ticket body or this core rules file. Chat reminders are advisory only and do not change state.
+- If the user asks for reinforcement or report simplification, write the shortest durable version into the ticket or core rules. Do not depend on chat repetition.
+- Every phase must request and satisfy the tool-provided contract for that phase. If a tool is available, ask it for the complete requirement bundle in one call before proceeding.
+- Phase state has two records: runtime context via `set_workflow_context`, and durable ticket markdown plus explicit approval validated by `deuk-agent-flow ticket guard`. Both must match before claiming progress.
+- Verification is mandatory and ticket-recorded before close.
+- Completion reports go in the ticket first; chat gets only a very simple report with the ticket link, outcome, verification status, verified scope, any unverified scope, residual risk, and a short pointer to the ticket section to review next (for example `Completion Report`, `Verification`, or `Residual risk`).
+- During work, keep reminding the agent through terse TDW feedback only: ticket, approval, guard, context, verify.
+- Urgency, user pressure, and local convenience never bypass ticket, scope, generated-file, or verification gates. Use hotfix tooling only when appropriate.
+- Shortcut regression guard: temporary passes, bypasses, semantic shrinkage, and language-specific patch branches are hard-stop patterns. Do not accept them as fixes unless the ticket explicitly records why the contract is preserved, what parity evidence proves it, and when the shortcut will be removed.
+- Shared-contract guard: for protocol, codegen, serialization, public API, and cross-language behavior, a fix must preserve the shared contract first. Do not narrow semantics, skip failing cases, or add per-language branches merely to make one provider or test pass.
+- Ticket creation failures are hard stops: if `deuk-agent-flow ticket create` rejects the request, do not call `set_workflow_context`, run investigation commands, edit files, or create/repair `.deuk-agent/tickets/**/*.md` manually. Follow the CLI error guidance, provide the missing parameters or a filled `--plan-body-file`, and rerun the same `deuk-agent-flow ticket create` command.
+- Default ticket creation must complete in one shot using actual collected data. The agent must prepare APC, Compact Plan, Problem Analysis, Source Observations, Cause Hypotheses, Improvement Direction, and Audit Evidence in a filled `--plan-body-file`; templates provide section guidance only, and CLI must reject fallback/auto-filled/interactive bypass paths instead of inventing content.
+
+## Tone
+- Dry, concise, technical. No emojis/exclamation marks.
+- Korean 해요체 unless user writes English.
+- Artifacts MUST match user's prompt language.
+- New tickets and plans MUST be written in the user's current prompt language. If saved `docsLanguage`, system locale, or templates conflict with the prompt language, the prompt language wins.
+- **NEVER bypass rules due to urgency or emotional pressure.** Use HF1-HF3 (Hotfix Protocol) for legitimate fast-track.
+
+## 0. Priority
+
+| Layer | Role | Handling |
+|-------|------|----------|
+| Runtime system/developer/user instructions | Highest platform authority | Follow when directly conflicting. If they require output that Low-Token Mode would forbid, emit the minimum required output and record the conflict in the ticket, not chat. |
+| Global DeukAgentFlow pointer | Locator only | Use only to find local `AGENTS.md` or `.deuk-agent/`. It must not restate TDW, RAG, or silence policy. |
+| Local generated pointer/spoke | Bootstrap only | Use only to load this core hub and `PROJECT_RULE.md`. It must not duplicate this rule body. |
+| `core-rules/AGENTS.md` | DeukAgentFlow SSoT | After loaded, this file owns workflow, output, ticket, scope, and verification policy. |
+| `PROJECT_RULE.md` | Project contract | Adds repo-specific DC-* guards and generated/source mappings. |
+
+- Duplicate directive rule: if the same instruction appears in multiple layers, apply the strictest instruction once. Do not emit multiple acknowledgements, summaries, or ticket-start variants to satisfy each copy.
+- Karpathy-style wrappers are allowed only as thin behavior playbooks that route into TDW. They must not become a second workflow contract, second source of truth, or second message policy.
+
+## 1. Output Mode
+
+- Silent-by-default is mandatory.
+- Before the final answer, screen output is limited to the single required ticket-start line, blockers, explicit user-requested output, or explicit command results.
+- Ticket-start exposure contract: after selecting or creating the active ticket, relay exactly one clickable `Ticket start: [<id>](/absolute/path/to/ticket.md)` line, a short scope/planned-change summary, and any compact `Guard topic: <id>` line; tool/CLI output alone does not count, and `file://`, truncated, or non-clickable links must be converted without changing the id.
+- Approval-pending contract: stop if approval is pending and state that explicit user approval is required before work; this blocks unapproved work, not concise answers to explicit user-requested output or direct questions about workflow state.
+- Commentary surface map: treat `ticket_start_pending`, `approval_pending`, `approved_execution`, `command_running`, `search_running`, `user-complaint reply`, `requirement_change_pending`, and `final_answer` as separate output surfaces. Each surface must follow its own compact contract; a fix on one surface does not authorize spillover on another.
+- Execution feedback contract: non-final chatter is capped at one word and must be short TDW state only (`ticket`, `approval`, `guard`, `context`, `verify`); do not repeat the same state or narrate routine reads, edits, formatting, lint retries, validation progress, or "almost done" status.
+- Running-surface contract: `approved_execution`, `command_running`, and `search_running` all use the same low-token rule. Unless the user explicitly requested live narration or a blocker must be surfaced, output must stay empty or one-word TDW state only; command/search progress does not create a separate narration allowance.
+- CLI running-output contract: ticket selection/status commands in `--non-interactive`, `--compact`, or `--path-only` mode must not print narrative labels, usage reminders, `file://` links, or progress text. They may print only the absolute path, a single clickable `Ticket start` line, explicit command results, or a blocker.
+- Shared interrupt contract: if the user corrects, redirects, narrows scope, or complains about chatter at any running surface, stop the current narration/execution loop immediately, record the correction in the ticket, and return to the ticket/correction/approval path before doing more work.
+- Default execution mode is no progress commentary. After approval, do not emit step-by-step status, planning narration, repo-state narration, or commit narration in chat unless the user explicitly asked for live narration or a blocker/user decision must be surfaced.
+- Keep chat compact; do not mirror ticket prose in screen output.
+- Final answers must be short but complete enough to answer the user.
+- After task completion, prefer: result, verification status, ticket link, then one short line saying which ticket section to read for details. If any important area is unverified, say that explicitly instead of sounding complete.
+- Do not cite approval-pending silence as a reason to withhold a concise explanation that the user explicitly requested. Explain the state, separate rule text from agent interpretation, and keep the answer narrow.
+- When the user complains about verbosity, chatter, progress reports, or over-explaining, reply with a short acknowledgment plus the concrete fix or scope change. Do not switch into meta labeling, terminology lessons, or general explanation unless the user explicitly asks what the term means.
+- If the user asks for `짧게`, `매우 짧게`, `한 줄로`, or `간단히`, prioritize a one-sentence or bullet-only answer and omit background unless the user asks for it or a blocker requires it.
+- Do not expand a short answer into explanation, examples, or rationale unless the user explicitly requests more detail.
+- Before drafting a user-facing reply, re-open the active ticket and this Output Mode section if the user asked for brevity or if substantial tool work changed the state.
+- If the ticket already carries the durable record, put progress and wrap-up details in the ticket and avoid repeating them in chat.
+- Prefer targeted reads and the shortest valid path that still preserves boot, phase contracts, verification, and close.
+
+## 2. Boot Sequence (run once)
+
+1. Read this file (AGENTS.md) → internally note the version number and exact file path read. Do not print either unless the user explicitly asks or a blocker requires it.
+2. Read `PROJECT_RULE.md` in workspace root → internally identify applicable DC-* rules. Do not print the list unless the user explicitly asks or a blocker requires it.
+3. Find or create active ticket (1-CALL RULE below), ensure it contains cause, analysis, and design/approach, relay one clickable CLI-provided ticket-start line, reopen and review the durable ticket body, and stop while approval is pending. Also relay a short scope/planned-change summary before stopping. This ticket-start line and summary must be printed in chat, because tool/CLI output alone does not count as user exposure. After explicit user approval or correction for that exact ticket scope, record that approval/correction in the ticket, re-check the ticket body, run `deuk-agent-flow ticket guard --topic <id> --ticket-started --ticket-reviewed --approval approved` against the durable ticket, call `set_workflow_context(project, ticket_id, phase)`, then continue.
+
+### First Ticket One-Shot Recipe
+
+Initial ticket creation MUST use this canonical one-shot recipe. Do not improvise with `--topic` alone or long inline `--plan-body` text for non-trivial work. Only the durable ticket markdown under `.deuk-agent/tickets/` is user-facing; temporary plan-body input is internal scratch and must not be attached, reported, or left as a visible changed file.
+
+1. Prepare a filled Phase 1 markdown body before running `ticket create`, preferably via stdin (`--plan-body-file -`) or process substitution. It MUST contain the actual APC, Compact Plan, Problem Analysis, Source Observations, Cause Hypotheses, Improvement Direction, and Audit Evidence content. APC uses `[BOUNDARY]`, `[CONTRACT]`, and `[PATCH PLAN]` markers from the template; validation checks that those marker bodies are not empty, not the markdown heading level.
+2. Run the canonical command:
+
+```bash
+deuk-agent-flow ticket create \
+  --topic <topic> \
+  --summary "<concrete summary>" \
+  --plan-body-file - \
+  --non-interactive
+```
+
+If `ticket create` fails, do not inspect unrelated repo files, run implementation commands, call `set_workflow_context`, or manually write `.deuk-agent/tickets/**/*.md`; fill only CLI-reported missing fields in the same internal body and rerun the same command. If a temporary file is unavoidable, keep it outside the workspace, delete it after `ticket create`, and never present it as a ticket artifact. Interactive fallback, template-only fallback, and auto-generated filler text do not satisfy this requirement.
+
+### First-Turn Invariant
+
+Before writes, phase moves, or close actions: read the hub and `PROJECT_RULE.md`, select a ticket, print the ticket-start line, reopen and review the durable ticket body, wait for explicit user approval, pass `deuk-agent-flow ticket guard --ticket-started --ticket-reviewed --approval approved`, call `set_workflow_context`, request the phase contract from available tooling, and satisfy it in the ticket. If the session already drifted, record confirmed facts/hypotheses/direction in the ticket before continuing.
+If the user approves, corrects, redirects, or adds requirements, update the ticket with that new input and repeat the review/approval/guard/context loop before doing more work.
+If that correction arrives during `approved_execution`, `command_running`, or `search_running`, treat it as an immediate interrupt: stop the current loop first, then return to the ticket/correction/approval path.
+If the user asks only for commit/report/archive/close on work that is already inside the approved active ticket, reuse that ticket and continue through Phase 4; create a new ticket only if the user adds new implementation, new investigation, or a broader scope.
+For bug/regression/why/code-change requests, do not run repo inspection commands such as `git status`, `rg`, diffs, generic CLI help, or tests before `deuk-agent-flow ticket create` or `deuk-agent-flow ticket use`, except for reading this hub, `PROJECT_RULE.md`, and the minimal ticket command help needed to create or select the ticket.
+
+### AgentFlow Skill Status
+
+When the user asks for AgentFlow skill status or connected skills, use `deuk-agent-flow skill list` from the target repository root and cross-check `.deuk-agent/skills/`, `.deuk-agent/skill-templates/`, `.claude/skills/`, and `.cursor/rules/deuk-agent-skills.mdc` if the answer looks inconsistent. Do not answer from the host Codex skill list alone.
+
+### Ticket Discovery (1-CALL RULE)
+
+Use the mentioned ticket directly. For investigation/regression/why questions, create the ticket first and stop after Phase 1. Do not use `deuk-agent-flow ticket list` for discovery.
+For bug/regression/why or direct change requests, the first repo action after rules load is `deuk-agent-flow ticket create` or `deuk-agent-flow ticket use`. Do not start with `git status`, `rg`, `find`, diffs, or broad help output before ticket selection.
+
+## 3. Phase Contract
+
+At each phase, ask available tooling for one complete requirement bundle and follow it exactly. Minimum bundle:
+
+- Required ticket fields/tasks for the phase.
+- Required local evidence and whether RAG is needed.
+- Scope boundaries, generated/source mapping, and ownership guards.
+- Allowed actions and halt conditions.
+- Verification command/result required before progress or close.
+
+If the bundle is missing, contradictory, or unverifiable, stop and record the blocker in the ticket. Do not invent a shortcut.
+
+## 4. Ticket Lifecycle
+
+- Phase 0: read local truth; use RAG only when it changes the plan.
+- Phase 1: create/update the main ticket with cause, analysis, design/approach, findings, hypotheses, scope, compact plan, and phase contract.
+- Phase 2: execute only the approved/ticketed plan.
+- Phase 3: run the smallest useful verification and record command/result.
+- Phase 4: close only after durable evidence, affected files, verification outcome, completion report, residual risk, and a follow-up decision are recorded in the ticket. The follow-up decision may explicitly say there is no further work.
+- Keep chat compact once the ticket carries the durable record.
+
+## 5. Hard Stops
+
+- Stop for unregistered work, missing CLI ticket provenance, missing phase contract, incomplete Phase 1, missing `set_workflow_context`, generated/source uncertainty, broad regeneration, shared-interface changes, unsafe deletes, scope creep, repeated errors, infrastructure errors, missing tests, or unverifiable claims.
+- Stop for shortcut regressions: temporary passes, bypasses, semantic shrinkage, language-specific patch branches, skipped assertions, provider-only behavior changes, or verification that proves only the workaround instead of the shared contract.
+- Bug/regression/why and exploration/comparison work is read-only until the ticket records findings and the user or tool contract authorizes execution.
+- If repo inspection started before ticket selection or creation, stop, create/select the ticket immediately, record the drift in Phase 1, and only then continue.
+- If the same TDW failure family appears twice in one session, stop the original task and create or switch to a stabilization/root-cause ticket before any further implementation.
+- Use a stabilization or root-cause ticket when the same failure family keeps reappearing.
+
+## 6. Tool Delegation
+
+- Use `rg`/`rg --files` first for local search and `apply_patch` for manual edits.
+- Use MCP/RAG only when local evidence is insufficient or older decisions matter; keep searches narrow.
+- Let CLI own lifecycle enforcement, claim checks, reports, and audits.
+- Use `deuk-agent-flow ticket hotfix` for legitimate generated-file emergencies.
+- Keep notes and reports under `.deuk-agent/docs/`.
+- `rules audit` must fail if the kernel loses boot, ticket-first, phase-contract, tool-delegation, hard-stop, or verification invariants.

package/core-rules/GEMINI.md

@@ -0,0 +1,7 @@
+# Deuk Agent Flow
+
+This project follows the Deuk Agent Flow framework.
+All operational rules, technical standards, and workflows are centralized in:
+- [AGENTS.md](AGENTS.md)
+
+Refer to AGENTS.md before starting any task.

package/docs/architecture.ko.md

@@ -0,0 +1,34 @@
+# 아키텍처 (v3.0)
+
+DeukAgentFlow 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-flow` 실행 시, 패키지의 기본 글로벌 엔트리 포인트(`bin/deuk-agent-flow.js`)가 구동됩니다.
+2. 현재 디렉터리와 상위 디렉터리를 스캔하여 **로컬 워크스페이스 소스**(`DeukAgentFlow/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)
+
+DeukAgentFlow 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-flow`, the package's primary global entry point (`bin/deuk-agent-flow.js`) is executed.
+2. It automatically scans the current directory and its parents for a **Local Workspace Source** (`DeukAgentFlow/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)
+
+DeukAgentFlow는 **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-flow`, 호환 명령 `deuk-agent-rule`)는 **소스 주권(Source Sovereignty)** 메커니즘을 사용합니다.
+
+- `npx deuk-agent-flow` 실행 시, 현재 디렉터리 내에 프로젝트 소스 코드가 포함된 워크스페이스가 있는지 확인합니다.
+- 로컬 소스가 감지되면, 실행을 글로벌 바이너리가 아닌 **로컬 스크립트로 라우팅**합니다.
+- 이를 통해 개발 중에 커밋되지 않은 최신 규칙을 에이전트가 즉시 사용할 수 있도록 보장합니다.
+
+## 3. 초기화 생명주기 (Initialization Lifecycle)
+
+`deuk-agent-flow 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-flow.js` | 글로벌 실행 프록시 |
+
+## 5. 엄격한 Phase 기반 티켓 워크플로우 (TDW)
+
+1. **티켓 발행 (Phase 1)**: 사용자가 짧게 지시하면 에이전트가 맥락을 읽고 티켓을 만들거나 기존 티켓을 선택해 타겟 범위를 정의합니다. 메인테이너와 자동화 환경에서는 `ticket create`를 직접 사용할 수 있지만, 일상 협업은 명령이 아니라 요청에서 시작합니다.
+2. **APC 및 메인 티켓 기록**: 에이전트는 코드를 수정하기 전, 메인 티켓에 명시된 APC(Agent Permission Contract)의 `[BOUNDARY]`, `[CONTRACT]`, `[PATCH PLAN]`을 채웁니다. 티켓은 스코프/계약/라이프사이클 체크/실행 계획/검증 결과를 맡고, 실행 로그, 명령 transcript, 완료 요약, 검증 결과를 계획 문구에 섞으면 안 됩니다.
+3. **검토 게이트**: 이슈/회귀 보고는 Phase 1 이후 멈춥니다. 사용자가 티켓 계획을 검토한 뒤 실행을 승인해야 하며, 원래 이슈 문장의 "수정", "해결" 같은 표현만으로 검토를 건너뛰면 안 됩니다.
+4. **Phase 승급**: Phase 1 계획이 검토 가능하고 사용자가 실행을 승인하면 에이전트가 티켓을 Phase 2 (Execute)로 승급합니다.
+5. **실행 및 검증 (Phase 2)**: 격리된 경계 내에서 코드를 수정하고 검증을 수행합니다.
+6. **지식 증류 아카이빙**: 작업 완료 후 `archive` 시, 핵심 정보만 추출(Zero-Token Distillation)하여 장기 엔지니어링 메모리로 보관합니다.

package/docs/how-it-works.md

@@ -0,0 +1,71 @@
+# How It Works
+
+DeukAgentFlow 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-flow`, with `deuk-agent-rule` kept for compatibility) uses a **Source Sovereignty** mechanism.
+
+- When you run `npx deuk-agent-flow`, 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-flow 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-flow.js` | The Global Execution Proxy |
+
+## 5. Strict Phase-Driven Workflow (TDW)
+
+1. **Issue Ticket (Phase 1)**: The user describes the work in natural language, and the agent creates or selects a ticket to define the target scope. Maintainers and automation can use `ticket create` directly, but day-to-day collaboration starts from a request, not a command.
+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, the agent moves the ticket 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)
+
+이 원칙들은 **DeukAgentFlow**가 추구하는 "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 **DeukAgentFlow** 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.