deuk-agent-flow 4.2.7 → 5.0.2

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

@@ -1,52 +1,109 @@
-# 작동 원리 (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/` | 제한된 실행 계약서 (작업 지시서) |
-| `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)하여 장기 엔지니어링 메모리로 보관합니다.
+# 작동 원리 (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/` | 제한된 실행 계약서 (작업 지시서) |
+| `templates/` | 티켓, 규칙, 스킬 템플릿의 패키지 소유 단일 진실 공급원 |
+| `bin/deuk-agent-flow.js` | 글로벌 실행 프록시 |
+
+## 5. Ticket Workflow: CLI가 소유하는 상태 테이블
+
+DeukAgentFlow는 티켓 생명주기를 느슨한 help 문구와 phase flag 묶음이 아니라 로컬 상태 테이블로 다룹니다. 이것은 범용 workflow runtime이 아닙니다. CLI가 state, transition, recipe assembly, DocMeta validation을 소유합니다.
+
+이 소유권은 선언적 문구가 아니라 end-to-end 런타임 책임을 뜻합니다. 에이전트가 보는 prompt를 CLI가 출력하고, registry/ticket-store context를 해석하고, project/RAG context를 붙이고, 어떤 approval gate와 다음 state가 유효한지 CLI가 결정합니다. ticket markdown과 registry 저장소는 런타임을 위한 durable artifact이지, 병렬적인 워크플로우 진실 공급원이 아닙니다.
+
+| 계층 | 진실 공급원 | 런타임 역할 |
+|---|---|---|
+| Lifecycle 선언 | `scripts/ticket-workflow.mjs` | state, phase/status 메타, 허용 transition, recipe id, template id, project policy role 선언 |
+| State prompt | `docs/cli-surfaces/state/*.md` | 현재 state가 에이전트에게 무엇을 의미하는지 안내 |
+| State template | `docs/cli-surfaces/state-template/*.md` | 해당 state에서 작성해야 할 슬롯과 종료 조건 제시 |
+| Project policy | `.deuk-agent/project-guardrails/*.md` | analysis, coding, debugging, approval, completion 같은 역할별 프로젝트 제약 추가 |
+| Durable record | `.deuk-agent/tickets/**/*.md` | scoped ticket record, evidence, 본문 `## DocMeta` 계약, compact frontmatter summary 저장 |
+
+에이전트가 state에 진입하거나 상태를 확인하면 CLI는 이 조각들을 하나의 DocMeta state surface로 구성합니다.
+
+```text
+Ticket workflow state
+  -> localized state recipe
+  -> project policy metadata
+  -> source contract
+  -> compact flow:[workspace:state] action line
+```
+
+그래서 `deuk-agent-flow rules ticket --workspace <workspace-id>`는 여러 파일을 에이전트가 따로 읽게 하지 않고 조합된 ticket rule surface를 출력합니다. `ticket use`, `ticket status`, `ticket move`, `ticket guard`도 일반 help가 아니라 state-machine command로 봐야 합니다.
+
+### 전이 엔진
+
+티켓 상태 변경은 workflow transition resolver가 계산합니다.
+
+1. 현재 티켓 frontmatter의 `phase/status`를 읽습니다.
+2. 이를 `phase1`, `phase2`, `phase3`, `phase4` 같은 workflow state로 매핑합니다.
+3. `--next`, `--phase`, 또는 `phase2` 같은 명시 gate에서 target state를 계산합니다.
+4. workflow state table에 선언되지 않은 transition이면 차단합니다.
+5. target `phase/status`를 반환하고, 명령이 ticket file과 index를 갱신합니다.
+
+예:
+
+| 현재 | 명령 의도 | Workflow transition | 결과 |
+|---|---|---|---|
+| `phase1/open` | 승인된 실행 | `phase1 -> phase2` | `phase=2`, `status=active` |
+| `phase2/active` | next | `phase2 -> phase3` | `phase=3`, `status=active` |
+| `phase3/active` | 종료 가능 | `phase3 -> phase4` | `phase=4`, `status=closed` |
+| `phase4/closed` | 재오픈 | `phase4 -> phase1` | `phase=1`, `status=open` |
+
+중요한 경계는 prompt text가 state를 결정하지 않는다는 점입니다. state는 lifecycle 선언과 CLI transition engine이 결정하고, recipe는 결정된 state 안에서 LLM 행동을 안내합니다.
+
+### 티켓 DocMeta 저장 구조
+
+티켓 frontmatter는 의도적으로 작게 유지합니다. `id`, `phase`, `status`, `docmetaStatus`, `docmetaValidation`, `docmetaTarget`, 짧은 error key처럼 사람과 index가 바로 읽는 필드만 둡니다. 전체 DocMeta 객체를 frontmatter에 저장하면 안 됩니다.
+
+전체 DocMeta 계약은 티켓 본문의 마지막 섹션인 `## DocMeta` 아래에 저장합니다. 이 하단 블록이 required slot, source map, validation detail, output status, adapter contract를 소유합니다. CLI 명령은 본문 계약을 먼저 갱신하고, 사람이 큰 YAML 헤더를 읽지 않아도 티켓 상태를 추적할 수 있도록 frontmatter에는 작은 요약만 mirror합니다.
+
+기본 command output은 compact projection만 렌더링해야 합니다. 전체 DocMeta는 `--status-detail`, `--verbose`, `--json`, audit output처럼 명시적인 상세 모드에서만 드러냅니다.
+
+이 경계는 디버깅과 리팩터링에도 그대로 적용됩니다. 이 워크플로우가 깨졌다면 기본 대응은 parser나 파일 배치 한 군데를 손보는 국소 패치가 아니라, visible command behavior, state transition wiring, context attachment, approval gate, regression coverage를 함께 복구하는 CLI 계약 수리입니다.
+
+## 6. 엄격한 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

@@ -1,71 +1,128 @@
-# 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) |
-| `templates/` | Package-owned SSoT for ticket, rule, and skill templates |
-| `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
-```
+# 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) |
+| `templates/` | Package-owned SSoT for ticket, rule, and skill templates |
+| `bin/deuk-agent-flow.js` | The Global Execution Proxy |
+
+## 5. Ticket Workflow: CLI-Owned State Table
+
+DeukAgentFlow treats the ticket workflow as a local state table rather than a set of loose help text and phase flags. It is not a general workflow runtime. The CLI owns state, transitions, recipe assembly, and DocMeta validation.
+
+That ownership is end-to-end, not rhetorical. The CLI surface is the workflow runtime: it emits the prompt seen by the agent, resolves registry and ticket-store context, attaches project/RAG context, and decides which approval gate or next state is valid. Ticket markdown and registry storage are durable artifacts for the runtime, not a parallel workflow authority.
+
+| Layer | Source of truth | Runtime role |
+|---|---|---|
+| Workflow declaration | `scripts/ticket-workflow.mjs` | Declares states, phase/status metadata, allowed transitions, recipe ids, template ids, and project policy roles |
+| State prompts | `docs/cli-surfaces/state/*.md` | Tells the agent what the current state means |
+| State templates | `docs/cli-surfaces/state-template/*.md` | Shows the write slots and exit condition for that state |
+| Project policies | `.deuk-agent/project-guardrails/*.md` | Adds role-specific project constraints such as analysis, coding, debugging, approval, and completion |
+| Durable record | `.deuk-agent/tickets/**/*.md` | Stores the scoped ticket record, evidence, body `## DocMeta` contract, and compact frontmatter summary |
+
+The CLI builds one DocMeta state surface when an agent enters or inspects a state:
+
+```text
+Ticket workflow state
+  -> localized state recipe
+  -> project policy metadata
+  -> source contract
+  -> compact flow:[workspace:state] action line
+```
+
+This is why `deuk-agent-flow rules ticket --workspace <workspace-id>` prints a combined ticket rule surface instead of asking the agent to manually read several files. It is also why `ticket use`, `ticket status`, `ticket move`, and `ticket guard` should be treated as state-machine commands, not as generic helpers.
+
+### Transition Engine
+
+Ticket state changes are resolved by the workflow transition resolver:
+
+1. Read the current ticket `phase/status` from frontmatter.
+2. Map it to a workflow state such as `phase1`, `phase2`, `phase3`, or `phase4`.
+3. Resolve the requested target state from `--next`, `--phase`, or an explicit gate such as `phase2`.
+4. Reject transitions that are not declared in the workflow state table.
+5. Return the target `phase/status` and let the command update the ticket file and index.
+
+Examples:
+
+| Current | Command intent | Workflow transition | Result |
+|---|---|---|---|
+| `phase1/open` | approved execution | `phase1 -> phase2` | `phase=2`, `status=active` |
+| `phase2/active` | next | `phase2 -> phase3` | `phase=3`, `status=active` |
+| `phase3/active` | close-ready | `phase3 -> phase4` | `phase=4`, `status=closed` |
+| `phase4/closed` | reopen | `phase4 -> phase1` | `phase=1`, `status=open` |
+
+The important boundary is that prompt text does not decide state. The workflow declaration and CLI transition engine decide state; recipes only guide the LLM once the state is known.
+
+### Ticket DocMeta Storage
+
+Ticket frontmatter is intentionally small. It stores human/index fields such as `id`, `phase`, `status`, `docmetaStatus`, `docmetaValidation`, `docmetaTarget`, and short error keys. It must not store the full DocMeta object.
+
+The full DocMeta contract is stored as the final ticket body section under `## DocMeta`. That bottom block owns required slots, source maps, validation details, output status, and adapter contracts. CLI commands update the body contract first, then mirror a compact summary to frontmatter so humans can scan ticket state without reading a large YAML header.
+
+Default command output should render the compact projection only. Full DocMeta is for explicit detail modes such as `--status-detail`, `--verbose`, `--json`, or audit-oriented output.
+
+The same boundary applies to debugging and refactoring. If this workflow breaks, the fix is not a narrow parser or file-layout tweak by default; it is an end-to-end CLI contract repair spanning visible command behavior, state transition wiring, context attachment, approval gates, and regression coverage.
+
+## 6. 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, workflow 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.
+
+## 7. 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 workflow 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 workflow 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 +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)
-
-한국어와 영어 문서는 단일 모델의 거울 쌍이어야 합니다.
-
-- **이유**: 엔지니어링 팀은 다국어 환경인 경우가 많습니다. 문서 간 내용이 어긋나면 워크플로우 파편화가 발생합니다.
+# 원칙 (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)
+
+한국어와 영어 문서는 단일 모델의 거울 쌍이어야 합니다.
+
+- **이유**: 엔지니어링 팀은 다국어 환경인 경우가 많습니다. 문서 간 내용이 어긋나면 워크플로우 파편화가 발생합니다.