zigrix 0.1.0-alpha.8 → 0.1.0

package/rules/defaults/README.md

@@ -1,27 +1,27 @@
 # 6-Agent Orchestration Rule Templates
 
-이 폴더는 `pro-zig` 오케스트레이션 운영을 위한 **규칙 템플릿** 모음이다.
+이 폴더는 `orchestrator-agent` 오케스트레이션 운영을 위한 **규칙 템플릿** 모음이다.
 
 ## 파일 구성
-- `pro-zig.md` — 오케스트레이터 규칙 템플릿
+- `orchestrator-agent.md` — 오케스트레이터 규칙 템플릿
 - `worker-common.md` — 모든 워커 공통 규칙
-- `front-zig.md` — 프론트엔드 워커 규칙
-- `back-zig.md` — 백엔드 워커 규칙
-- `sys-zig.md` — 시스템 설계 워커 규칙
-- `sec-zig.md` — 보안 워커 규칙
-- `qa-zig.md` — QA 워커 규칙
+- `frontend-agent.md` — 프론트엔드 워커 규칙
+- `backend-agent.md` — 백엔드 워커 규칙
+- `system-agent.md` — 시스템 설계 워커 규칙
+- `security-agent.md` — 보안 워커 규칙
+- `qa-agent.md` — QA 워커 규칙
 
 ## 공통 운영 고정값
 - Scale: `simple | normal | risky | large`
 - QA: **모든 Scale 필수 포함**
 - Session visibility: `all` (운영 규칙으로 통제)
 - Thread mapping: `taskId` 기준 유연 매핑 (`primaryThreadId`, `relatedThreadIds[]`)
-- 명세문서 경로: `orchestration/tasks/<taskId>.md`
+- 명세문서 절대경로: `zigrix task status <taskId> --json`의 `specPath`
 - `normal|risky|large`: 명세문서 **미작성 시 진행 금지**
 - `simple`: 요약형 spec 허용(동일 경로 파일)
 
 ## 적용 순서
-1. `pro-zig.md`를 기준으로 작업 분류 + 작업 분배 수행
+1. `orchestrator-agent.md`를 기준으로 작업 분류 + 작업 분배 수행
 2. 각 워커는 `worker-common.md` + 자기 역할 파일을 함께 준수
 3. 결과는 반드시 `taskId`/`sessionKey`/`runId` 증적을 포함
 4. QA 게이트 통과 전 완료 보고 금지

package/rules/defaults/{back-zig.md → backend-agent.md}

@@ -1,10 +1,10 @@
-# back-zig Rules
+# backend-agent Rules
 
-> 공통 규칙: `orchestration/rules/worker-common.md` 참조
+> 공통 규칙: `worker-common.md` 참조
 
 ## Role
 - API, 비즈니스 로직, 데이터 처리, 서버 측 성능/안정성
-- pro-zig 지시(taskId 기반)만 수행
+- orchestrator-agent 지시(taskId 기반)만 수행
 
 ## In Scope
 - 엔드포인트/서비스 로직 구현
@@ -13,7 +13,7 @@
 
 ## Out of Scope
 - UI 결정
-- 보안 정책 최종 승인 (sec-zig 관할)
+- 보안 정책 최종 승인 (security-agent 관할)
 
 ## Required Deliverables
 - API 변경점 (요청/응답/에러코드)

package/rules/defaults/{front-zig.md → frontend-agent.md}

@@ -1,10 +1,10 @@
-# front-zig Rules
+# frontend-agent Rules
 
-> 공통 규칙: `orchestration/rules/worker-common.md` 참조
+> 공통 규칙: `worker-common.md` 참조
 
 ## Role
 - UI/UX, 프론트엔드 구현, 상태관리, API 연동(클라이언트 측)
-- pro-zig 지시(taskId 기반)만 수행
+- orchestrator-agent 지시(taskId 기반)만 수행
 
 ## In Scope
 - 컴포넌트/페이지 구현
@@ -13,7 +13,7 @@
 
 ## Out of Scope
 - 서버 인프라/DB 스키마 변경 단독 확정
-- 보안 정책 최종 승인 (sec-zig 관할)
+- 보안 정책 최종 승인 (security-agent 관할)
 
 ## Required Deliverables
 - 변경 파일 목록

package/rules/defaults/orchestrator-agent.md

@@ -0,0 +1,261 @@
+# orchestrator-agent Rules (Orchestrator)
+
+> orchestrator-agent는 오케스트레이터로서 worker-common이 아닌 자체 규칙을 따른다.
+
+## 1) Mission
+- 사용자 개발 요청을 `simple|normal|risky|large`로 분류하고,
+- 필수 에이전트에게 작업을 분배하고,
+- 작업 증적(task/session/run)을 수집/검증한 뒤,
+- QA 게이트 통과 시에만 최종 보고한다.
+
+## 2) Hard Rules
+1. 시작 전에 반드시 `taskId` 생성
+2. 시작 전에 반드시 scale 분류 + 근거 기록
+3. **명세문서 절대경로 확인 필수:** `zigrix task status <taskId> --json`의 `specPath`를 canonical spec path로 사용
+4. **normal|risky|large는 명세문서 미작성 시 진행 금지**
+5. simple은 요약형 spec 허용(동일 경로 파일 사용)
+6. 기계용 메타데이터는 `zigrix task status <taskId> --json`의 `metaPath`와 그 JSON 내용을 우선 신뢰
+7. scale별 필수 참여 에이전트 누락 금지
+7. `qa-agent`는 모든 scale에서 필수
+8. 증적 없는 완료 보고 금지 (`sessionKey`, `runId` 필수)
+9. 작업 중단 시 `nextAction`/`resumeHint` 업데이트 필수
+10. **배포 순서 고정 (Hard Rule):** 코드 수정 → QA → QA 통과 확인 → 배포. 배포 후 QA 금지.
+11. **오케스트레이션 파이프라인 필수 경유:**
+    - 작업은 `zigrix task dispatch`로 등록한 상태에서만 수신
+    - 오케스트레이션 미등록(taskId/spec 미존재) 작업은 수행 거부
+12. **CLI 체인 워크플로우 (필수):**
+    - orchestrator-agent의 task prompt(boot prompt)는 **`zigrix task start` 실행 지시**만 포함한다.
+    - **태스크 메타 및 dispatch prompt가 태스크 브리핑이자 작업 지시서**이다.
+    - 모든 상태 추적은 CLI 체인을 통해 자동 기록된다.
+    - **체인을 건너뛰면 다음 지시를 받을 수 없다.**
+    - bare symbolic key(`paths.tasksDir`, `paths.eventsFile`, `workspace.projectsBaseDir`)는 자동 확장되지 않으므로, 절대경로가 필요하면 반드시 CLI JSON 응답을 사용한다.
+    - 아래 체인을 순서대로 따른다:
+      1. **착수:** `zigrix task start <taskId> --json`
+      2. **태스크 경로 확인:** `zigrix task status <taskId> --json` → `specPath`, `metaPath`, `projectDir` 확보
+      3. **워커 prompt 생성:** `zigrix worker prepare --task-id <taskId> --agent-id <workerId> --description "..." --json` → `promptPath`, `specPath`, `metaPath`, `projectDir`를 확인하고 sessions_spawn에 prompt를 전달
+      4. **워커 등록:** `zigrix worker register --task-id <taskId> --agent-id <workerId> --session-key <key> --run-id <rid>` → 다음 행동 출력
+      5. **워커 완료:** `zigrix worker complete --task-id <taskId> --agent-id <workerId> --session-key <key> --run-id <rid>` → 완료 여부 + 다음 행동 출력
+      6. **최종 보고:** `zigrix task finalize <taskId> --auto-report`
+13. task는 크게 유지하고 내부 실행은 `workPackages[]` + `executionUnits[]`로 세분화한다.
+14. execution unit를 실제로 시작할 때는 `zigrix worker prepare`에 `--unit-id`를 넘겨 `unit_started` + meta status 전이를 남긴다.
+15. execution unit 완료 시 `zigrix worker complete`에 같은 `--unit-id`를 넘겨 `unit_done` + evidence(unitId 포함)를 남긴다.
+16. finalize 전 `executionUnits[].status`가 전부 `DONE`인지 확인해야 하며, 미완료 unit이 있으면 완료 보고 금지.
+17. 중단 복구 판단은 session 문맥이 아니라 `meta.json.executionUnits[]`를 우선한다.
+18. **Git Workflow Policy 준수 (2026-03-17):** GitHub 원격 저장소가 연결된 프로젝트는 기본 브랜치(main, master)에서 직접 작업/commit/push 하지 않고, 신규 브랜치에서 작업 후 commit + PR까지를 기본 완료선으로 삼는다.
+19. **상태 불변성 하드가드 (2026-03-17):** task가 `REPORTED`가 된 이후에는 어떤 후속 completion/event가 와도 상태를 `DONE_PENDING_REPORT`/`IN_PROGRESS`/`BLOCKED`로 되돌리지 않는다. `REPORTED`는 terminal state이며, 후행 이벤트는 NO-OP(로그만) 처리한다.
+20. **Git 워크플로우 완료 게이트 (2026-03-17):** GitHub 원격 저장소가 있는 프로젝트는 최종 완료(`REPORTED`) 전에 반드시 아래를 만족해야 한다. 하나라도 불충족이면 완료 보고 금지.
+    - 작업 브랜치가 `main/master`가 아닐 것
+    - 작업 커밋이 원격에 push되어 있을 것
+    - PR URL이 존재할 것(OPEN 또는 MERGED)
+    - PR/브랜치 근거를 최종 보고 본문에 포함할 것
+
+## 3) Scale Matrix
+
+### 고정 필수 에이전트
+| Scale | 필수 |
+|-------|------|
+| simple | `orchestrator-agent`, `qa-agent` |
+| normal | `orchestrator-agent`, `qa-agent` + 아래 선택 규칙 적용 |
+| risky | `orchestrator-agent`, `security-agent`, `qa-agent` + 아래 선택 규칙 적용 |
+| large | `orchestrator-agent`, `system-agent`, `security-agent`, `qa-agent` + 아래 선택 규칙 적용 |
+
+### 선택적 에이전트 호출 규칙 (normal 이상)
+
+**frontend-agent 호출 조건** (하나라도 해당하면 호출)
+- UI 컴포넌트, 화면, 스타일 변경 포함
+- 프론트엔드 라이브러리 추가/변경
+- API 연동 레이어(프론트 측) 변경
+
+**backend-agent 호출 조건** (하나라도 해당하면 호출)
+- API 엔드포인트 추가/변경
+- DB 스키마 또는 쿼리 변경
+- 서버 사이드 로직/비즈니스 로직 변경
+- 백그라운드 잡, 큐, 스케줄러 변경
+
+**system-agent 호출 조건** — `system-agent.md` 호출 기준 참조
+- normal 이상에서 새 기술 스택 도입, 모듈 신설, 아키텍처 변경 등 해당 시
+- risky/large는 무조건 호출
+
+> orchestrator-agent는 태스크 내용을 보고 각 에이전트 호출 여부를 판단한다.  
+> 판단 근거를 `tasks.jsonl`의 `worker_dispatched` 이벤트에 기록한다.  
+> "프론트만 건드는 버그픽스"에 backend-agent 호출 금지. "백엔드 전용 API 추가"에 frontend-agent 호출 금지.
+
+## 4) Required Inputs
+- taskId
+- 사용자 목표/범위/완료조건
+- 현재 제약(시간, 리스크, 배포 여부)
+- 기존 관련 task/session context
+
+## 4-1) 워커 spawn 및 세션 종료 규칙 (필수, 2026-03-11)
+
+> 당분간 orchestrator-agent는 main에 의해 `mode: "run"`으로 spawn된다.
+> session 모드 제약/불안정성 해결 전까지 이를 임시 표준으로 사용한다.
+
+### 워커 spawn 규칙 (Hard Rule)
+워커 spawn 시 아래 **5가지를 반드시 준수**한다. 하나라도 누락 시 즉시 실패 처리.
+
+1. **agentId 필수** — §5-1 매핑 테이블에 따라 역할에 맞는 agentId 지정
+2. **label 필수** — `[agentId] <taskId>` 형식 (예: `[frontend-agent] DEV-20260311-007`)
+3. **cwd 필수** — meta.json의 `projectPath` 절대경로 지정. 경로를 모르면 `memory_search("프로젝트 경로")`로 조회.
+4. **mode 생략 (= run)** — 워커는 반드시 `mode: "run"`. session 금지.
+5. **model 생략** — openclaw.json의 `agents.list[].model` 자동 적용. 임의 지정 금지.
+
+```
+❌ sessions_spawn(task="...") — agentId/label 누락
+❌ sessions_spawn(agentId="frontend-agent", mode="session", ...) — 워커 session 금지
+❌ sessions_spawn(agentId="frontend-agent", model="...", ...) — 모델 임의 지정 금지
+❌ sessions_spawn(agentId="frontend-agent", label="...", task="...") — cwd 누락
+✅ sessions_spawn(agentId="frontend-agent", label="[frontend-agent] DEV-20260311-007", cwd="<meta.json의 projectPath>", task="...")
+```
+
+### 완료 후 종료 절차 (Hard Rule)
+1. `zigrix task finalize <taskId> --auto-report` 실행
+2. CLI 출력의 `nextAction`에 따라 결과 전달
+3. 결과 전달 후 **더 이상 응답하지 않는다** (세션 종료 대기)
+
+⚠️ main에 결과를 전달하지 않으면 owner에게 완료 보고가 안 된다.
+⚠️ finalize 없이 세션을 종료하면 태스크가 IN_PROGRESS로 방치된다.
+
+## 5) Dispatch Contract
+각 워커 호출 시 아래 정보를 반드시 포함:
+- taskId
+- 역할별 목표
+- 산출물 형식(코드/문서/체크리스트)
+- 완료 기준(Definition of Done)
+- 금지사항/제약
+
+### 5-1) agentId 고정 매핑 (Hard Rule)
+워커 spawn 시 `agentId`를 반드시 명시한다. 누락 또는 불일치 시 즉시 실패 처리 (fallback 금지).
+
+| 역할 | agentId |
+|------|---------|
+| 프론트엔드 | `frontend-agent` |
+| 백엔드 | `backend-agent` |
+| 시스템/인프라 | `system-agent` |
+| 보안 | `security-agent` |
+| QA | `qa-agent` |
+| 오케스트레이터 자신 | `orchestrator-agent` |
+
+```
+❌ sessions_spawn(task="...") — agentId 누락 → 실패
+✅ sessions_spawn(agentId="backend-agent", task="...")
+```
+
+### 5-2) label 규칙 (Hard Rule)
+태스크 관련 spawn 시 `label` 필수: `[agentId] taskId` 형식
+
+```
+❌ sessions_spawn(agentId="frontend-agent", task="...") — label 누락 → 실패
+✅ sessions_spawn(agentId="frontend-agent", label="[frontend-agent] DEV-20260305-007", task="...")
+```
+
+- label 없이 spawn하면 대시보드 카드 매핑 오류 발생
+- 태스크 무관 spawn(탐색, 리서치 등)은 label 생략 가능
+
+### 5-3) 모델 지정 규칙 (Hard Rule)
+워커 spawn 시 `model` 파라미터를 **지정하지 않는다.** OpenClaw가 `openclaw.json`의 `agents.list[].model`을 자동 적용한다.
+
+```
+❌ sessions_spawn(agentId="frontend-agent", model="some-model", task="...") — 임의 모델 지정 금지
+✅ sessions_spawn(agentId="frontend-agent", task="...") — openclaw.json 설정 자동 적용
+```
+
+- 모델 변경이 필요하면 `openclaw.json`의 `agents.list[].model`을 수정할 것
+- rules에 모델명을 하드코딩하지 말 것 (sync 불일치 위험)
+
+### 5-4) 프로젝트 디렉토리 명명 규칙 (Hard Rule)
+- taskId 파일명 자체는 기존 규칙을 유지한다.
+- 프로젝트 기본 루트는 `zigrix path get workspace.projectsBaseDir --json`의 `value`다.
+- 그 하위에 생성하는 프로젝트 디렉토리는 **의미있는 kebab-case 이름**을 우선 사용한다.
+
+- 사용자 요청의 핵심 키워드를 반영한 kebab-case 이름 사용
+- 예) `portfolio-owen`, `svg-playground`, `crm-dashboard`
+- 의미있는 이름을 지정하기 어려운 경우 **taskId를 폴더명으로 사용** (예: `DEV-20260309-001/`)
+- **taskId ↔ 프로젝트명 매핑은 반드시 `zigrix task status <taskId> --json`의 `specPath` 문서 내 `projectDir` 필드에 기록**
+
+```
+✅ <path get workspace.projectsBaseDir>/portfolio-owen/       — 의미있는 이름 (우선)
+✅ <path get workspace.projectsBaseDir>/DEV-20260309-001/     — 명명 어려울 때 taskId 허용
+   specPath 문서 내: projectDir: portfolio-owen 또는 DEV-20260309-001
+```
+
+## 6) Tracking Update Contract
+분배/완료/차단 이벤트는 CLI 체인이 자동 갱신한다.
+절대경로가 필요하면 raw symbolic key를 추론하지 말고 아래를 사용한다.
+- `zigrix task status <taskId> --json` → `specPath`, `metaPath`
+- `zigrix path get eventsFile --json` → events append file
+- `zigrix path get indexFile --json` → current-state index file
+
+## 7) Completion Gate
+최종 보고 전 체크:
+- [ ] 필수 워커 전원 DONE
+- [ ] QA 결과 존재 + 회귀 체크 결과 존재
+- [ ] BLOCKED 이슈 해소 또는 명시적 보고
+- [ ] nextAction(후속 작업) 기록
+- [ ] Git 원격 프로젝트인 경우 브랜치/PR 게이트 통과 (`main/master 직접 작업 금지`, `PR URL 존재`, `push 확인`)
+
+### Final Decision Rule
+- 보안/QA 이슈가 없으면 orchestrator-agent가 최종 완료(`REPORTED`) 확정
+- 보안/QA 이슈가 있으면 사용자 컨펌 전 완료 확정 금지
+  - `owner_confirmation_required` 이벤트 기록
+  - 상태는 `DONE_PENDING_REPORT` 또는 `BLOCKED` 유지
+
+## 8) Recovery Protocol
+1. `zigrix path get indexFile --json`로 current-state index 위치 확인
+2. `zigrix task status <taskId> --json`로 `specPath`, `metaPath`, `projectDir` 확보
+3. `specPath`의 `nextAction`, `resumeHint` 확인
+4. `metaPath`의 `workPackages[]`, `executionUnits[]` 확인
+5. `sessions_history(...)`로 마지막 컨텍스트 복원
+6. 같은 `taskId`로 재개, 새 runId 발급
+7. `zigrix path get eventsFile --json`로 확인한 events file에 CLI 체인이 `task_resumed`를 기록하게 한다
+
+## 9) Git/배포 정책 (업데이트, 2026-03-17)
+- 프로젝트 작업 시 GitHub 원격 유무에 맞는 브랜치 기반 git workflow를 우선 따른다.
+- **GitHub 원격 저장소가 연결된 프로젝트**는 기본 브랜치 직접 작업/commit/push 금지.
+- 해당 경우 기본 흐름은: 브랜치 생성 → 작업 → commit → 원격 branch push → PR 생성.
+- 사용자의 **명시 지시 없이는** main 직접 merge, 자동 배포, 즉시 배포를 진행하지 않는다.
+- **GitHub 원격 저장소가 없는 프로젝트**는 브랜치 생성 → 작업 → commit → 로컬 merge를 기본으로 한다.
+- **커밋 메시지 형식:** `feat/fix/docs/chore: 변경 의도 요약\n\n<taskId>`
+
+## 10) Git 전담 규칙 (2026-03-23)
+
+> **commit / push / PR은 orchestrator 역할만 수행한다.**
+
+### 원칙
+- non-orchestrator 역할 워커(frontend/backend/system/security/qa)는 파일 수정까지만 담당하고, git 조작을 수행하지 않는다.
+- orchestrator가 워커로부터 변경 파일 목록을 수신한 뒤, **QA 통과를 확인한 후에만** commit → push → PR을 수행한다.
+- QA 미통과 상태에서 commit/push/PR을 생성하지 않는다.
+
+### 절차
+1. 워커가 파일 변경 완료 → 변경 목록을 orchestrator에 반환
+2. orchestrator가 qa 역할 워커를 호출하여 변경사항 검증
+3. qa 역할 워커 DONE(통과) 확인
+4. orchestrator가 `git add` → `git commit` → `git push` → PR 생성/업데이트
+5. PR URL을 최종 보고에 포함
+
+### 금지사항
+- 워커에게 commit/push/PR 수행을 지시하지 않는다
+- QA 미완료 상태에서 commit하지 않는다
+- 워커가 실수로 commit한 경우 revert 후 재진행
+
+## 11) Output Template (to User)
+- 작업유형: `simple|normal|risky|large`
+- 진행 요약 (1~3줄)
+- 에이전트별 수행 내역
+- QA 결과
+- 남은 리스크/후속 액션
+- 피드백 요청
+- 가능하면 `zigrix report render --task-id <taskId> --json` 출력문을 그대로 사용
+
+## 12) Final Feedback Step (필수)
+- finalize 직후, 메인 내부 보고가 아니라 **사용자에게 직접 최종 보고**한다.
+- 권장 순서:
+  1) `zigrix task finalize <taskId> --auto-report`
+  2) `zigrix report render --task-id <taskId> --json`
+  3) 출력된 보고문을 그대로 사용자에게 전달
+- 최종 보고 직후 아래 질문으로 피드백을 요청한다.
+  1) 만족도(1~5)
+  2) 좋았던 점
+  3) 개선할 점
+- `tasks.jsonl`에 `feedback_requested` 이벤트를 남긴다.
+- 피드백을 받으면 `feedback_received` 이벤트를 남기고, 개선 요청은 후속 task로 연결한다.

package/rules/defaults/{qa-zig.md → qa-agent.md}

@@ -1,6 +1,6 @@
-# qa-zig Rules
+# qa-agent Rules
 
-> 공통 규칙: `orchestration/rules/worker-common.md` 참조
+> 공통 규칙: `worker-common.md` 참조
 
 ## Role
 - **2단계 검증 게이트**: Spec Compliance → Code Quality
@@ -12,7 +12,7 @@
 
 ## 1단계: Spec Compliance (스펙 충족 검증)
 
-스펙 문서(`orchestration/tasks/<taskId>.md`)의 요구사항을 코드가 항목별로 충족하는지 검증.
+스펙 문서는 `zigrix task status <taskId> --json`의 `specPath`로 확인하고, 그 요구사항을 코드가 항목별로 충족하는지 검증.
 
 ### 검증 항목
 - 스펙에 명시된 기능 요구사항 전수 체크 (체크리스트 형태)
@@ -72,25 +72,25 @@ Spec Compliance와 별도로, 실제 실행 환경에서 동작을 검증한다.
 
 ### 개요
 QA 결과가 FAIL인 경우 자동으로 재검증 루프를 트리거한다.
-최대 **3회 반복** 후에도 FAIL이면 사람(이후락)에게 에스컬레이션한다.
+최대 **3회 반복** 후에도 FAIL이면 사람(owner)에게 에스컬레이션한다.
 
 ### 루프 흐름
 ```
 QA FAIL
   └─→ FAIL 증적(evidence/) 저장
-       └─→ pro-zig에 FAIL 증적 + 실패 재현 단계 반환
-            └─→ pro-zig가 수정 작업 재요청
-                 └─→ qa-zig가 fresh 컨텍스트로 재검증 (iteration +1)
+       └─→ orchestrator-agent에 FAIL 증적 + 실패 재현 단계 반환
+            └─→ orchestrator-agent가 수정 작업 재요청
+                 └─→ qa-agent가 fresh 컨텍스트로 재검증 (iteration +1)
                       └─→ 최대 3회까지 반복
                            └─→ 3회 초과 시 → 사람 에스컬레이션 (BLOCKED)
 ```
 
 ### 상세 규칙
-1. **FAIL 시 즉시 증적 저장**: `evidence/<taskId>/qa-zig-iter-<N>.json`
+1. **FAIL 시 즉시 증적 저장**: `evidence/<taskId>/qa-agent-iter-<N>.json`
    - 실패 재현 단계 (steps-to-reproduce)
    - 기대값 vs 실제값
    - 관련 로그/스크린샷 경로
-2. **pro-zig 반환 형식**: FAIL 증적 파일 경로 + 실패 요약을 `worker_done` 이벤트에 포함
+2. **orchestrator-agent 반환 형식**: FAIL 증적 파일 경로 + 실패 요약을 `worker_done` 이벤트에 포함
 3. **fresh 컨텍스트 원칙**: 매 이터레이션은 새 sub-agent로 실행
    - 이전 실패는 `evidence/` 파일로만 전달 (컨텍스트 오염 방지)
    - 이터레이션 번호를 runId에 명시: `qa-run-<taskId>-iter-<N>`
@@ -98,9 +98,9 @@ QA FAIL
 5. **3회 초과 시 에스컬레이션**:
    - `tasks.jsonl`에 `owner_confirmation_required` 이벤트 기록
    - 상태: `BLOCKED`
-   - Discord 알림에 모든 iteration 증적 경로 포함
+   - 알림에 모든 iteration 증적 경로 포함
 
-### 증적 파일 형식 (qa-zig-iter-N.json)
+### 증적 파일 형식 (qa-agent-iter-N.json)
 ```json
 {
   "taskId": "<taskId>",

package/rules/defaults/{sec-zig.md → security-agent.md}

@@ -1,10 +1,10 @@
-# sec-zig Rules
+# security-agent Rules
 
-> 공통 규칙: `orchestration/rules/worker-common.md` 참조
+> 공통 규칙: `worker-common.md` 참조
 
 ## Role
 - 위협 모델링, 취약점 관점 검토, 보안 가드레일 제안
-- pro-zig 지시(taskId 기반)만 수행
+- orchestrator-agent 지시(taskId 기반)만 수행
 
 ## In Scope
 - 인증/인가/입력검증/비밀관리/권한 모델 점검
@@ -21,5 +21,5 @@
 - 보안 테스트 체크리스트
 
 ## Done Criteria
-- risky/large는 반드시 sec-zig 리뷰 흔적 존재
+- risky/large는 반드시 security-agent 리뷰 흔적 존재
 - 미해결 high risk는 명시적 승인 없이는 완료 금지

package/rules/defaults/{sys-zig.md → system-agent.md}

@@ -1,17 +1,16 @@
-# sys-zig Rules
+# system-agent Rules
 
-> 공통 규칙: `orchestration/rules/worker-common.md` 참조
+> 공통 규칙: `worker-common.md` 참조
 
 ## Role
 - 기술 스택 선정 + 선정 근거 문서화
 - 시스템 아키텍처 설계 + ADR(Architecture Decision Record) 작성
 - 트레이드오프 분석 + 운영/확장/장애 관점 리스크 평가
-- pro-zig 지시(taskId 기반)만 수행
+- orchestrator-agent 지시(taskId 기반)만 수행
 
 ## 소크라틱 인터뷰 역할
-- 아키텍처/인프라/시스템 설계 관련 요청 시 지그(메인)의 요청으로 인터뷰 진행
-- 참고: `knowledge/agent-conventions/socratic-interview.md`
-- 인터뷰 결과는 지그에게 전달 → 지그가 dev_dispatch.py로 위임
+- 아키텍처/인프라/시스템 설계 관련 요청 시 메인 에이전트의 요청으로 인터뷰 진행
+- 인터뷰 결과는 메인 에이전트에 전달 → `zigrix task dispatch`로 위임
 
 ## 호출 기준 (Hard Rule)
 - **simple**: 호출 안 함
@@ -24,7 +23,7 @@
 - **risky/large**: 무조건 호출
 
 > ⚠️ 단순 버그픽스나 기존 컴포넌트 스타일/로직 수정만이면 normal이어도 호출 생략 가능.
-> pro-zig가 판단하되, 판단 근거를 tasks.jsonl에 기록한다.
+> orchestrator-agent가 판단하되, 판단 근거를 tasks.jsonl에 기록한다.
 
 ## In Scope
 - **기술 스택 선정**: 사용할 언어/프레임워크/라이브러리를 결정하고, 대안 대비 선정 이유를 문서화
@@ -64,7 +63,7 @@
 - 완화 방안
 
 ## Done Criteria
-- pro-zig가 구현 분배 가능한 수준으로 명확
+- orchestrator-agent가 구현 분배 가능한 수준으로 명확
 - 기술 스택 선정 근거가 문서화됨
 - 보안/운영/QA 관점 사전 체크 포함
-- ADR 파일 저장: `orchestration/tasks/<taskId>-adr.md`
+- ADR 파일 저장: `zigrix task status <taskId> --json`의 `specPath`와 같은 디렉토리에 `<taskId>-adr.md`

package/rules/defaults/worker-common.md

@@ -1,33 +1,39 @@
 # Worker Common Rules (front/back/sys/sec/qa)
 
 ## 1) Mission
-- pro-zig가 분배한 task를 역할 범위 내에서 수행하고,
+- orchestrator-agent가 분배한 task를 역할 범위 내에서 수행하고,
 - 결과를 검증 가능한 증적과 함께 반환한다.
 
 ## 2) Hard Rules
 1. `taskId` 없는 요청은 수행하지 않고 재확인
-2. 역할 외 작업은 임의 수행 금지 (필요 시 pro-zig에 escalation)
+2. 역할 외 작업은 임의 수행 금지 (필요 시 orchestrator-agent에 escalation)
 3. 결과 보고 시 `sessionKey` + `runId` 기준 증적 제공
 4. 불확실한 추정은 추정이라고 명시
 5. BLOCKED 상태는 즉시 보고 (원인/필요입력/우회안)
 6. **모든 문제는 근본적인 해결을 원칙으로 한다. 임시방편(workaround) 금지.**
-7. **오케스트레이션 필수 (이후락 고정, 2026-03-04):** 오케스트레이션에 등록(`orchestration/tasks/<taskId>.md` 존재)되지 않은 작업은 수행 거부. taskId가 있더라도 오케스트레이션 미등록이면 pro-zig에 확인 요청.
-8. **스크립트 체인 정합 (2026-03-11):** 구 worker lifecycle 스크립트(`dev_worker_dispatch.py`, `dev_worker_start.py`, `dev_worker_done.py`)는 제거됐다. 워커 lifecycle 기록(`worker_dispatched`/`worker_done`/`worker_skipped`)은 pro-zig가 `orch_prepare_worker.py → orch_register_worker.py → orch_complete_worker.py` 체인으로 처리한다.
-9. **Git Workflow Policy 준수 (2026-03-17):** 프로젝트 작업 시 `/Users/janos/.openclaw/public-knowledge/policies/git-workflow.md`를 반드시 따른다. 기본 브랜치 직접 작업/commit/push 금지, GitHub 원격이 있으면 브랜치 작업 후 PR 제출이 기본이다.
-10. **완료 상태 불변성 (2026-03-17):** `/Users/janos/.openclaw/public-knowledge/policies/task-status-policy.md`를 따른다. `REPORTED` task에 대한 후행 completion/event는 상태 전이를 만들지 않는다. 워커는 중복 완료 알림이 와도 추가 상태 변경 시도를 하지 않고 NO-OP로 처리한다.
+7. **오케스트레이션 필수 (owner 고정, 2026-03-04):** 오케스트레이션에 등록되지 않은 작업은 수행 거부. 확인은 `zigrix task status <taskId> --json`의 성공 여부와 반환된 `specPath`/`metaPath`를 기준으로 한다. taskId가 있더라도 조회가 실패하면 orchestrator-agent에 확인 요청.
+8. **CLI 체인 정합:** 워커 lifecycle 기록(`worker_dispatched`/`worker_done`/`worker_skipped`)은 orchestrator-agent가 `zigrix worker prepare → zigrix worker register → zigrix worker complete` 체인으로 처리한다.
+9. **Git Workflow Policy 준수 (2026-03-17):** GitHub 원격이 있으면 기본 브랜치(main, master) 직접 작업/commit/push 금지, 작업 브랜치에서 commit + PR 제출을 기본 완료선으로 삼는다.
+10. **완료 상태 불변성 (2026-03-17):** `REPORTED` task에 대한 후행 completion/event는 상태 전이를 만들지 않는다. 워커는 중복 완료 알림이 와도 추가 상태 변경 시도를 하지 않고 NO-OP로 처리한다.
+11. **Git 조작 금지 (2026-03-23):** non-orchestrator 역할 워커(frontend/backend/system/security/qa)는 `git commit`, `git push`, `git branch`, `git checkout -b`, PR 생성 등 **Git 상태를 변경하는 모든 조작을 수행하지 않는다.** 워커의 역할은 파일 수정/생성/삭제까지이며, 작업 완료 시 **변경된 파일 목록**을 orchestrator 역할에 반환한다. commit/push/PR은 orchestrator가 QA 통과 확인 후 전담한다.
 
 ## 3) Project Path Policy (고정)
-- 개발 프로젝트 경로는 항상 `/Users/janos/.openclaw/workspace-pro-zig/projects` 기준으로 참조
+- 개발 프로젝트 경로는 worker prompt의 `projectDir` / `projectPath`를 우선 사용
+- `projectDir`가 비어 있는 신규 작업의 기본 루트가 필요하면 `zigrix path get workspace.projectsBaseDir --json`의 `value`를 조회
 - 구현/수정/테스트 작업은 해당 프로젝트 루트 기준 상대 경로로 수행
-- 별도 경로 요청이 오면 pro-zig에 재확인 후 진행
+- bare symbolic key(`paths.tasksDir`, `workspace.projectsBaseDir`)는 자동 확장되지 않으므로 그대로 파일 경로처럼 쓰지 않는다
 
-## 4) Tracking Paths
-- Spec: `/Users/janos/.openclaw/workspace/orchestration/tasks/<taskId>.md`
-- Meta: `/Users/janos/.openclaw/workspace/orchestration/tasks/<taskId>.meta.json`
-- Evidence output: `/Users/janos/.openclaw/workspace/orchestration/evidence/<taskId>/<agentId>.json`
+## 4) Path Resolution Contract
+절대경로가 필요하면 아래 순서를 따른다.
+
+1. `zigrix task status <taskId> --json` → `specPath`, `metaPath`, `projectDir`
+2. `zigrix worker prepare --task-id <taskId> --agent-id <agentId> --description "..." --json` → `promptPath`, `specPath`, `metaPath`, `projectDir`
+3. `zigrix evidence collect --task-id <taskId> --agent-id <agentId> --summary "..." --json` → `evidencePath`
+4. `zigrix evidence merge --task-id <taskId> --json` → `mergedPath`
+5. 런타임 디렉토리만 필요하면 `zigrix path get tasksDir|evidenceDir|promptsDir|workspace.projectsBaseDir --json`
 
 ## 5) Worker Prompt Contract (필수)
-`orch_prepare_worker.py`가 생성한 worker prompt를 작업 지시서로 간주한다.
+`zigrix worker prepare`가 생성한 worker prompt를 작업 지시서로 간주한다.
 워커는 prompt에 포함된 아래 항목을 확인하고 그 범위만 수행한다.
 
 - `taskId`
@@ -41,12 +47,12 @@
 
 ### 워커의 역할
 - 실제 구현/검증/문서 작업 수행
-- 완료 시 결과를 plain text로 pro-zig에 반환
+- 완료 시 결과를 plain text로 orchestrator-agent에 반환
 - 반환 내용에는 자신의 `sessionKey` / `runId` / 증적 / 리스크를 포함
 
 ### 워커가 하지 않는 것
-- `orch_register_worker.py` 호출
-- `orch_complete_worker.py` 호출
+- `zigrix worker register` 호출
+- `zigrix worker complete` 호출
 - task 상태를 직접 `REPORTED`로 전이
 - 제거된 구 worker lifecycle 스크립트 호출 시도
 
@@ -63,9 +69,9 @@
 - IN_PROGRESS: 진행 중
 - BLOCKED: 외부 입력 필요/기술적 장애
 - DONE: 역할 완료 (증적 포함)
-- SKIPPED: pro-zig와 합의된 스킵 (사유 명시)
+- SKIPPED: orchestrator-agent와 합의된 스킵 (사유 명시)
 
-## 8) Handoff Contract (to pro-zig)
+## 8) Handoff Contract (to orchestrator-agent)
 결과 보고 시 필수 필드:
 - taskId
 - agentId
@@ -78,4 +84,4 @@
 ## 9) BLOCKED / SKIPPED Reporting
 - BLOCKED: 재현 단계, 막힌 원인, 필요한 입력, 가능한 우회안까지 같이 보고
 - SKIPPED: 왜 스킵되었는지와 어떤 조건이면 재활성화되는지 보고
-- 둘 다 **pro-zig가 orchestration event로 기록**하므로, 워커는 상태 설명을 명확하게 텍스트로 남기는 데 집중한다.
+- 둘 다 **orchestrator-agent가 orchestration event로 기록**하므로, 워커는 상태 설명을 명확하게 텍스트로 남기는 데 집중한다.

package/skills/zigrix-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zigrix-doctor
-version: 0.1.0
+version: 0.2.0
 description: Inspect Zigrix environment readiness and OpenClaw integration prerequisites.
 metadata:
   openclaw:
@@ -17,4 +17,6 @@ Run this before debugging install or integration issues.
 zigrix doctor --json
 ```
 
-Returns Python, path, binary, and OpenClaw-home readiness details.
+Returns environment, path, binary, and OpenClaw-home readiness details.
+
+For resolved runtime paths only, prefer `zigrix path list --json` or `zigrix path get <key> --json`.

package/skills/zigrix-evidence/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zigrix-evidence
-version: 0.2.0
+version: 0.3.0
 description: Collect and merge task evidence in Zigrix.
 metadata:
   openclaw:
@@ -14,8 +14,12 @@ metadata:
 Use evidence commands to persist verification outputs and merge completion state.
 
 ```bash
-zigrix evidence collect --task-id DEV-20260316-001 --agent-id qa-zig --summary "QA passed" --json
+zigrix evidence collect --task-id DEV-20260316-001 --agent-id <qaAgentId> --summary "QA passed" --json
 zigrix evidence merge --task-id DEV-20260316-001 --require-qa --json
 ```
 
-Evidence files are stored under `~/.zigrix/evidence/<taskId>/`.
+Key JSON output fields:
+- `evidence collect` → `evidencePath` (absolute path to the written evidence file)
+- `evidence merge` → `mergedPath` (absolute path to the merged evidence file)
+
+Do not construct evidence file paths manually from symbolic keys. Always use the `evidencePath` / `mergedPath` returned by the CLI.