zigrix 0.1.1 → 0.2.1

package/dist/state/tasks.js

@@ -170,6 +170,45 @@ export function updateTaskStatus(paths, taskId, status) {
     rebuildIndex(paths);
     return task;
 }
+export function bindOrchestratorSession(paths, params) {
+    const task = loadTask(paths, params.taskId);
+    if (!task)
+        return null;
+    const parsed = parseAgentSubagentSessionKey(params.sessionKey);
+    if (parsed && parsed.agentId !== params.agentId) {
+        throw new Error(`orchestrator bind validation failed: sessionKey belongs to '${parsed.agentId}', expected '${params.agentId}'`);
+    }
+    const resolvedSessionId = params.sessionId ?? parsed?.sessionId ?? null;
+    task.orchestratorId = params.agentId;
+    task.orchestratorSessionKey = params.sessionKey;
+    if (resolvedSessionId) {
+        task.orchestratorSessionId = resolvedSessionId;
+    }
+    else {
+        delete task.orchestratorSessionId;
+    }
+    saveTask(paths, task);
+    appendEvent(paths.eventsFile, {
+        event: 'orchestrator_bound',
+        taskId: params.taskId,
+        phase: 'dispatch',
+        actor: 'zigrix',
+        targetAgent: params.agentId,
+        status: task.status,
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        payload: { agentId: params.agentId },
+    });
+    rebuildIndex(paths);
+    return {
+        ok: true,
+        taskId: params.taskId,
+        agentId: params.agentId,
+        sessionKey: params.sessionKey,
+        sessionId: resolvedSessionId,
+        status: task.status,
+    };
+}
 export function recordTaskProgress(paths, params) {
     const task = loadTask(paths, params.taskId);
     if (!task)
@@ -189,15 +228,226 @@ export function recordTaskProgress(paths, params) {
     rebuildIndex(paths);
     return event;
 }
-// ─── Stale policy ───────────────────────────────────────────────────────────
-export function findStaleTasks(paths, hours = 24) {
+function toNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+function parseAgentSubagentSessionKey(sessionKey) {
+    const matched = sessionKey.match(/^agent:([^:]+):subagent:([^:\s]+)$/);
+    if (!matched)
+        return null;
+    return { agentId: matched[1], sessionId: matched[2] };
+}
+function resolveSessionIdFromSessionsJson(agentsStateDir, agentId, sessionKey) {
+    try {
+        const sessionsJsonPath = path.join(agentsStateDir, agentId, 'sessions', 'sessions.json');
+        const raw = JSON.parse(fs.readFileSync(sessionsJsonPath, 'utf8'));
+        const entry = raw[sessionKey];
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            return null;
+        return toNonEmptyString(entry.sessionId);
+    }
+    catch {
+        return null;
+    }
+}
+function listDeletedSessionPaths(agentsStateDir, agentId, sessionId) {
+    const sessionsDir = path.join(agentsStateDir, agentId, 'sessions');
+    if (!fs.existsSync(sessionsDir))
+        return [];
+    const prefix = `${sessionId}.jsonl.deleted.`;
+    try {
+        return fs.readdirSync(sessionsDir)
+            .filter((name) => name.startsWith(prefix))
+            .sort((a, b) => b.localeCompare(a))
+            .map((name) => path.join(sessionsDir, name));
+    }
+    catch {
+        return [];
+    }
+}
+function collectTaskSessionRefs(task) {
+    const refs = [];
+    if (task.orchestratorSessionKey && task.orchestratorId) {
+        refs.push({
+            scope: 'orchestrator',
+            agentId: task.orchestratorId,
+            sessionKey: task.orchestratorSessionKey,
+            sessionId: task.orchestratorSessionId ?? null,
+        });
+    }
+    for (const [agentId, raw] of Object.entries(task.workerSessions ?? {})) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const data = raw;
+        const sessionKey = toNonEmptyString(data.sessionKey);
+        if (!sessionKey)
+            continue;
+        refs.push({
+            scope: 'worker',
+            agentId,
+            sessionKey,
+            sessionId: toNonEmptyString(data.sessionId),
+        });
+    }
+    return refs;
+}
+function diagnoseTaskSessions(task, agentsStateDir) {
+    if (!agentsStateDir)
+        return [];
+    return collectTaskSessionRefs(task).map((ref) => {
+        const parsed = parseAgentSubagentSessionKey(ref.sessionKey);
+        const agentId = parsed?.agentId ?? ref.agentId;
+        let resolvedSessionId = ref.sessionId;
+        let mappingSource = ref.sessionId ? 'explicit' : 'none';
+        if (!resolvedSessionId && parsed) {
+            resolvedSessionId = parsed.sessionId;
+            mappingSource = 'parsed';
+        }
+        if (!resolvedSessionId) {
+            const mappedSessionId = resolveSessionIdFromSessionsJson(agentsStateDir, agentId, ref.sessionKey);
+            if (mappedSessionId) {
+                resolvedSessionId = mappedSessionId;
+                mappingSource = 'sessions_json';
+            }
+        }
+        if (!resolvedSessionId) {
+            return {
+                scope: ref.scope,
+                agentId,
+                sessionKey: ref.sessionKey,
+                sessionId: null,
+                mappingSource,
+                state: 'missing',
+                reason: 'missing_session_mapping',
+                activePath: null,
+                deletedPath: null,
+            };
+        }
+        const activePath = path.join(agentsStateDir, agentId, 'sessions', `${resolvedSessionId}.jsonl`);
+        if (fs.existsSync(activePath)) {
+            return {
+                scope: ref.scope,
+                agentId,
+                sessionKey: ref.sessionKey,
+                sessionId: resolvedSessionId,
+                mappingSource,
+                state: 'active',
+                reason: null,
+                activePath,
+                deletedPath: null,
+            };
+        }
+        const deletedPaths = listDeletedSessionPaths(agentsStateDir, agentId, resolvedSessionId);
+        if (deletedPaths.length > 0) {
+            return {
+                scope: ref.scope,
+                agentId,
+                sessionKey: ref.sessionKey,
+                sessionId: resolvedSessionId,
+                mappingSource,
+                state: 'deleted',
+                reason: 'session_dead',
+                activePath: null,
+                deletedPath: deletedPaths[0],
+            };
+        }
+        return {
+            scope: ref.scope,
+            agentId,
+            sessionKey: ref.sessionKey,
+            sessionId: resolvedSessionId,
+            mappingSource,
+            state: 'missing',
+            reason: null,
+            activePath: null,
+            deletedPath: null,
+        };
+    });
+}
+function joinUniqueAgentIds(diagnoses, reason) {
+    const agentIds = Array.from(new Set(diagnoses.filter((item) => item.reason === reason).map((item) => item.agentId)));
+    return agentIds.join(', ') || 'unknown-agent';
+}
+function buildStaleGuidance(task, reasonCode, hours, diagnoses) {
+    if (reasonCode === 'session_dead') {
+        const agents = joinUniqueAgentIds(diagnoses, 'session_dead');
+        return {
+            reason: 'session_dead',
+            nextAction: `respawn the deleted OpenClaw session for ${agents} and re-register it before resuming ${task.taskId}`,
+            resumeHint: `start a fresh session for ${agents}, then update zigrix with the new session key/sessionId before continuing the blocked task`,
+            reportLine: `${task.taskId}: BLOCKED session_dead (${agents})`,
+        };
+    }
+    if (reasonCode === 'missing_session_mapping') {
+        const agents = joinUniqueAgentIds(diagnoses, 'missing_session_mapping');
+        return {
+            reason: 'missing_session_mapping',
+            nextAction: `repair or re-register the missing session mapping for ${agents} before resuming ${task.taskId}`,
+            resumeHint: `re-run worker/orchestrator registration with --session-key and --session-id so zigrix can resolve the backing OpenClaw session`,
+            reportLine: `${task.taskId}: BLOCKED missing_session_mapping (${agents})`,
+        };
+    }
+    return {
+        reason: 'stale_timeout',
+        nextAction: `inspect the latest progress for ${task.taskId} and either report, refresh progress, or respawn the worker after ${hours}h of inactivity`,
+        resumeHint: 'check task status/events/evidence, then continue with a fresh worker registration if the original session is no longer active',
+        reportLine: `${task.taskId}: BLOCKED stale_timeout (> ${hours}h)`,
+    };
+}
+function buildStaleTaskSummary(task, hours, agentsStateDir, fallbackReason = 'stale_timeout') {
     const cutoff = Date.now() - hours * 3600 * 1000;
-    return listTasks(paths).filter((task) => task.status === 'IN_PROGRESS' && Date.parse(task.updatedAt) < cutoff);
+    const timedOut = Date.parse(task.updatedAt) < cutoff;
+    const diagnoses = diagnoseTaskSessions(task, agentsStateDir);
+    const hasDeletedSession = diagnoses.some((item) => item.reason === 'session_dead');
+    const hasMissingMapping = diagnoses.some((item) => item.reason === 'missing_session_mapping');
+    if (!hasDeletedSession && !timedOut)
+        return null;
+    const reasons = new Set();
+    if (timedOut)
+        reasons.add('stale_timeout');
+    if (hasDeletedSession)
+        reasons.add('session_dead');
+    if (hasMissingMapping)
+        reasons.add('missing_session_mapping');
+    const reasonCode = hasDeletedSession
+        ? 'session_dead'
+        : hasMissingMapping && timedOut
+            ? 'missing_session_mapping'
+            : 'stale_timeout';
+    const guidance = buildStaleGuidance(task, reasonCode, hours, diagnoses);
+    const reason = reasonCode === 'stale_timeout' ? fallbackReason : guidance.reason;
+    return {
+        taskId: task.taskId,
+        title: task.title,
+        updatedAt: task.updatedAt,
+        hoursThreshold: hours,
+        timedOut,
+        reason,
+        reasonCode,
+        reasons: Array.from(reasons),
+        nextAction: guidance.nextAction,
+        resumeHint: guidance.resumeHint,
+        reportLine: guidance.reportLine,
+        sessions: diagnoses,
+    };
+}
+export function findStaleTasks(paths, hours = 24, options = {}) {
+    return listTasks(paths)
+        .filter((task) => task.status === 'IN_PROGRESS')
+        .map((task) => buildStaleTaskSummary(task, hours, options.agentsStateDir, options.fallbackReason ?? 'stale_timeout'))
+        .filter((task) => task !== null);
 }
-export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout') {
-    const staleTasks = findStaleTasks(paths, hours);
-    const changed = staleTasks.map((task) => {
+export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout', options = {}) {
+    const staleTasks = findStaleTasks(paths, hours, { ...options, fallbackReason: reason });
+    const changed = staleTasks.map((summary) => {
+        const task = loadTask(paths, summary.taskId);
+        if (!task)
+            return null;
         task.status = 'BLOCKED';
+        task.nextAction = summary.nextAction;
+        task.resumeHint = summary.resumeHint;
+        task.staleReason = summary.reasonCode;
+        task.staleReasons = summary.reasons;
         saveTask(paths, task);
         const event = appendEvent(paths.eventsFile, {
             event: 'task_blocked',
@@ -205,12 +455,33 @@ export function applyStalePolicy(paths, hours = 24, reason = 'stale_timeout') {
             phase: 'recovery',
             actor: 'zigrix',
             status: 'BLOCKED',
-            payload: { reason, previousStatus: 'IN_PROGRESS', hoursThreshold: hours },
+            payload: {
+                reason: summary.reason,
+                reasonCode: summary.reasonCode,
+                reasons: summary.reasons,
+                previousStatus: 'IN_PROGRESS',
+                hoursThreshold: hours,
+                timedOut: summary.timedOut,
+                nextAction: summary.nextAction,
+                resumeHint: summary.resumeHint,
+                reportLine: summary.reportLine,
+                sessions: summary.sessions,
+            },
         });
-        return { taskId: task.taskId, event };
-    });
+        return {
+            taskId: task.taskId,
+            reason: summary.reason,
+            reasonCode: summary.reasonCode,
+            reasons: summary.reasons,
+            nextAction: summary.nextAction,
+            resumeHint: summary.resumeHint,
+            reportLine: summary.reportLine,
+            sessions: summary.sessions,
+            event,
+        };
+    }).filter((item) => item !== null);
     rebuildIndex(paths);
-    return { ok: true, hours, reason, count: changed.length, changed };
+    return { ok: true, hours, requestedReason: reason, count: changed.length, changed };
 }
 // ─── Index ──────────────────────────────────────────────────────────────────
 export function rebuildIndex(paths) {

package/dist/state/verify.js

@@ -9,6 +9,12 @@ function safeReadJson(filePath) {
         return null;
     }
 }
+function sortedStrings(value) {
+    return Array.isArray(value) ? value.map(String).sort() : [];
+}
+function sameStringArray(left, right) {
+    return JSON.stringify([...left].sort()) === JSON.stringify([...right].sort());
+}
 function verifyTask(paths, task) {
     const issues = [];
     const evidenceDir = path.join(paths.evidenceDir, task.taskId);
@@ -17,34 +23,58 @@ function verifyTask(paths, task) {
     const presentEvidenceAgents = fs.existsSync(evidenceDir)
         ? fs.readdirSync(evidenceDir).filter((name) => name.endsWith('.json') && name !== '_merged.json').map((name) => path.basename(name, '.json')).sort()
         : [];
-    const requiredAgents = Array.isArray(task.requiredAgents) ? task.requiredAgents.map(String) : [];
+    const requiredAgents = Array.isArray(task.requiredAgents) ? task.requiredAgents.map(String).sort() : [];
     const workerAgents = Object.keys(task.workerSessions ?? {}).sort();
+    const requiredRoles = Array.isArray(task.requiredRoles) ? task.requiredRoles.map(String).sort() : [];
+    const roleAgentMap = task.roleAgentMap && typeof task.roleAgentMap === 'object'
+        ? task.roleAgentMap
+        : {};
     for (const agentId of requiredAgents) {
         if (!workerAgents.includes(agentId) && !presentEvidenceAgents.includes(agentId)) {
             issues.push(`required agent '${agentId}' has neither worker session nor evidence`);
         }
     }
+    for (const role of requiredRoles) {
+        const mappedAgents = Array.isArray(roleAgentMap[role]) ? roleAgentMap[role].map(String).filter(Boolean) : [];
+        if (mappedAgents.length === 0) {
+            issues.push(`required role '${role}' has no mapped agent in roleAgentMap`);
+            continue;
+        }
+        const hasActiveArtifact = mappedAgents.some((agentId) => requiredAgents.includes(agentId) || workerAgents.includes(agentId) || presentEvidenceAgents.includes(agentId));
+        if (!hasActiveArtifact) {
+            issues.push(`required role '${role}' has no required agent, worker session, or evidence`);
+        }
+    }
     if (merged) {
-        const mergedPresent = Array.isArray(merged.presentAgents) ? merged.presentAgents.map(String).sort() : [];
-        const mergedMissing = Array.isArray(merged.missingAgents) ? merged.missingAgents.map(String).sort() : [];
+        const mergedPresent = sortedStrings(merged.presentAgents);
+        const mergedMissing = sortedStrings(merged.missingAgents);
         const computedMissing = requiredAgents.filter((agentId) => !presentEvidenceAgents.includes(agentId)).sort();
-        if (JSON.stringify(mergedPresent) !== JSON.stringify(presentEvidenceAgents)) {
+        if (!sameStringArray(mergedPresent, presentEvidenceAgents)) {
             issues.push('merged presentAgents does not match evidence files');
         }
-        if (JSON.stringify(mergedMissing) !== JSON.stringify(computedMissing)) {
+        if (!sameStringArray(mergedMissing, computedMissing)) {
             issues.push('merged missingAgents does not match requiredAgents/evidence files');
         }
-        if (task.status === 'REPORTED' && merged.complete !== true) {
-            issues.push('task is REPORTED but merged evidence is incomplete');
+        const qaVerification = merged.qaVerification;
+        const qaVerificationComplete = Boolean(qaVerification &&
+            typeof qaVerification === 'object' &&
+            !Array.isArray(qaVerification) &&
+            qaVerification.complete === true);
+        if (['DONE_PENDING_REPORT', 'REPORTED'].includes(task.status) && merged.complete !== true) {
+            issues.push(`task is ${task.status} but merged evidence is incomplete`);
+        }
+        if (['DONE_PENDING_REPORT', 'REPORTED'].includes(task.status) && merged.qaPresent === true && !qaVerificationComplete) {
+            issues.push('task reached reporting state without DoD↔test verification mapping for QA evidence');
         }
     }
-    else if (task.status === 'REPORTED') {
-        issues.push('task is REPORTED but merged evidence is missing');
+    else if (['DONE_PENDING_REPORT', 'REPORTED'].includes(task.status)) {
+        issues.push(`task is ${task.status} but merged evidence is missing`);
     }
     return {
         taskId: task.taskId,
         status: task.status,
         requiredAgents,
+        requiredRoles,
         workerAgents,
         presentEvidenceAgents,
         mergedExists: Boolean(merged),
@@ -52,14 +82,62 @@ function verifyTask(paths, task) {
         issues,
     };
 }
+function verifyIndex(paths, tasks) {
+    const issues = [];
+    const index = safeReadJson(paths.indexFile);
+    if (!index) {
+        issues.push('index.json is missing or unreadable');
+        return { ok: false, issues };
+    }
+    const counts = index.counts && typeof index.counts === 'object' ? index.counts : {};
+    const statusBuckets = index.statusBuckets && typeof index.statusBuckets === 'object'
+        ? index.statusBuckets
+        : {};
+    const taskSummaries = index.taskSummaries && typeof index.taskSummaries === 'object'
+        ? index.taskSummaries
+        : {};
+    const activeTasks = index.activeTasks && typeof index.activeTasks === 'object'
+        ? index.activeTasks
+        : {};
+    if (Number(counts.tasks ?? -1) !== tasks.length) {
+        issues.push(`index counts.tasks mismatch: expected ${tasks.length}, got ${String(counts.tasks ?? 'missing')}`);
+    }
+    const expectedBuckets = new Map();
+    for (const task of tasks) {
+        expectedBuckets.set(task.status, [...(expectedBuckets.get(task.status) ?? []), task.taskId]);
+        const summary = taskSummaries[task.taskId];
+        if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+            issues.push(`taskSummaries missing entry for ${task.taskId}`);
+            continue;
+        }
+        if (summary.status !== task.status) {
+            issues.push(`taskSummaries status mismatch for ${task.taskId}`);
+        }
+    }
+    for (const [status, taskIds] of expectedBuckets.entries()) {
+        const indexed = sortedStrings(statusBuckets[status]);
+        if (!sameStringArray(indexed, taskIds)) {
+            issues.push(`statusBuckets mismatch for ${status}`);
+        }
+    }
+    const expectedActiveStatuses = new Set(['OPEN', 'IN_PROGRESS', 'BLOCKED', 'DONE_PENDING_REPORT']);
+    const expectedActiveTaskIds = tasks.filter((task) => expectedActiveStatuses.has(task.status)).map((task) => task.taskId).sort();
+    const indexedActiveTaskIds = Object.keys(activeTasks).sort();
+    if (!sameStringArray(indexedActiveTaskIds, expectedActiveTaskIds)) {
+        issues.push('activeTasks mismatch with task statuses');
+    }
+    return { ok: issues.length === 0, issues };
+}
 export function verifyState(paths) {
     const tasks = listTasks(paths);
     const checks = tasks.map((task) => verifyTask(paths, task));
     const failures = checks.filter((item) => item.ok === false);
+    const indexCheck = verifyIndex(paths, tasks);
     return {
-        ok: failures.length === 0,
+        ok: failures.length === 0 && indexCheck.ok === true,
         taskCount: tasks.length,
-        failedCount: failures.length,
+        failedCount: failures.length + (indexCheck.ok === true ? 0 : 1),
         checks,
+        index: indexCheck,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigrix",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "description": "Multi-project parallel task orchestration CLI for agent-assisted development",
   "license": "Apache-2.0",
@@ -70,11 +70,11 @@
     "@inquirer/prompts": "^8.3.2",
     "bcryptjs": "^2.4.3",
     "commander": "^14.0.0",
-    "next": "^15.2.3",
+    "next": "^15.5.15",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-markdown": "^10.1.0",
-    "yaml": "^2.8.1",
+    "yaml": "^2.8.3",
     "zod": "^4.1.5"
   },
   "devDependencies": {

package/rules/defaults/orchestrator-agent.md

@@ -1,6 +1,7 @@
 # orchestrator-agent Rules (Orchestrator)
 
 > orchestrator-agent는 오케스트레이터로서 worker-common이 아닌 자체 규칙을 따른다.
+> 이 문서 안의 `frontend-agent`/`backend-agent`/`qa-agent`/`orchestrator-agent` 표기는 **role label 예시**다. 실제 runtime agentId는 dispatch overlay의 `roleAgentMap`, `orchestratorId`, `qaAgentId`를 따른다.
 
 ## 1) Mission
 - 사용자 개발 요청을 `simple|normal|risky|large`로 분류하고,
@@ -23,7 +24,8 @@
 11. **오케스트레이션 파이프라인 필수 경유:**
     - 작업은 `zigrix task dispatch`로 등록한 상태에서만 수신
     - 오케스트레이션 미등록(taskId/spec 미존재) 작업은 수행 거부
-12. **CLI 체인 워크플로우 (필수):**
+12. **메인 전용 스킬 사용 금지:** `zigrix-main-agent-guide`는 main agent 전용이며, orchestrator runtime 세션은 dispatch prompt + Zigrix role rule만 canonical instruction으로 사용한다.
+13. **CLI 체인 워크플로우 (필수):**
     - orchestrator-agent의 task prompt(boot prompt)는 **`zigrix task start` 실행 지시**만 포함한다.
     - **태스크 메타 및 dispatch prompt가 태스크 브리핑이자 작업 지시서**이다.
     - 모든 상태 추적은 CLI 체인을 통해 자동 기록된다.
@@ -33,7 +35,7 @@
       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>` → 다음 행동 출력
+      4. **워커 등록:** `zigrix worker register --task-id <taskId> --agent-id <workerId> --session-key <key> --label <spawnLabel> --project-dir <projectDir> --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[]`로 세분화한다.

package/rules/defaults/worker-common.md

@@ -1,5 +1,7 @@
 # Worker Common Rules (front/back/sys/sec/qa)
 
+> 이 문서 안의 역할명은 role label 기준이다. 실제 runtime agentId / projectDir / task context는 worker overlay prompt를 우선 따른다.
+
 ## 1) Mission
 - orchestrator-agent가 분배한 task를 역할 범위 내에서 수행하고,
 - 결과를 검증 가능한 증적과 함께 반환한다.
@@ -13,6 +15,7 @@
 6. **모든 문제는 근본적인 해결을 원칙으로 한다. 임시방편(workaround) 금지.**
 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. **메인 전용 스킬 사용 금지:** `zigrix-main-agent-guide`는 main agent 전용이며, worker runtime 세션은 worker overlay prompt + Zigrix role rule만 canonical instruction으로 사용한다.
 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 통과 확인 후 전담한다.

package/skills/oz/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: oz
+version: 0.2.0
+description: Official OpenClaw Zigrix entrypoint. Force Zigrix delegation when a message starts with `/oz`, and semantically route plain-language requests to hand work off, assign it, or have Zigrix take it instead of doing the work directly.
+metadata:
+  openclaw:
+    requires:
+      bins: ["zigrix"]
+    cliHelp: "zigrix task dispatch --help"
+---
+
+# /oz — OpenClaw Zigrix Entrypoint
+
+Use this skill when either of the following is true:
+
+1. the user message starts with `/oz `
+2. the user is clearly asking, in natural language, to have work **delegated / handed off / assigned / orchestrated through Zigrix** instead of having the current main agent do it directly
+
+This skill is the public OpenClaw-facing entrypoint for Zigrix after `zigrix onboard` installs bundled skills.
+
+## 1) Route selection
+
+### `/oz` prefix
+If the message starts with `/oz `, treat it as:
+- `route = delegate`
+- `delegateMode = force`
+
+Remove the `/oz` prefix and use the remaining text as the delegation payload.
+
+### Natural-language delegation
+If there is no `/oz` prefix, judge the user's intent **semantically**.
+
+- Use the full meaning of the request and nearby context.
+- Do **not** rely on keyword tables or regex lists as the decision mechanism.
+- When helpful, read:
+  - `references/routing-rubric.md`
+  - `references/examples.md`
+
+Classify the turn into one of:
+- `delegate`
+- `direct`
+- `answer`
+
+### Semantic routing policy
+- Choose **`delegate`** when the user wants work to be handed off, assigned, orchestrated, or otherwise run through Zigrix rather than performed directly by the current main agent.
+- Choose **`direct`** only when the user explicitly wants the current agent to do it directly.
+- Choose **`answer`** when the user is asking for explanation, status, architecture, policy, or other non-execution discussion.
+- If the request is ambiguous but points toward tracked execution / implementation / multi-step change, bias toward `delegate` unless the user explicitly asked for direct execution.
+
+## 2) Delegate flow
+
+If `route = delegate`, use the canonical Zigrix handoff chain:
+
+1. Turn the user request into:
+   - `title`
+   - `description`
+   - `scale`
+   - optional `projectDir`
+2. Run:
+
+```bash
+zigrix task dispatch \
+  --title "..." \
+  --description "..." \
+  --scale simple|normal|risky|large \
+  --project-dir /path/to/project \
+  --json
+```
+
+3. Read the JSON result and extract:
+   - `taskId`
+   - `orchestratorId`
+   - `orchestratorPrompt`
+   - `projectDir`
+4. Spawn the orchestrator with the returned prompt.
+
+Preferred pattern:
+
+```text
+sessions_spawn(
+  agentId: <orchestratorId>,
+  mode: "session",
+  thread: true when the current surface supports stable Zigrix thread orchestration, otherwise false,
+  label: "[<orchestratorId>] <taskId>",
+  task: <orchestratorPrompt>,
+  cwd: <projectDir when present>
+)
+```
+
+5. Reply briefly with the handoff result (`taskId`, orchestrator/session/thread info).
+
+## 3) Delegate-only guard
+
+Once this skill decides `route = delegate`:
+- do **not** directly implement the task
+- do **not** directly edit/write project files as a substitute for Zigrix handoff
+- do **not** fallback to direct execution if dispatch or spawn fails
+
+If dispatch or spawn fails:
+- report the failure clearly
+- include the failing step
+- stop there
+
+## 4) Empty or underspecified payloads
+
+If `/oz` is used but the remaining payload is empty or too underspecified to create a task:
+- ask the user to restate the task in one clear sentence
+- do not silently guess
+- do not direct-execute instead
+
+## 5) Direct / answer cases
+
+If semantic routing chooses:
+- `direct` → current agent may proceed with direct execution
+- `answer` → answer normally without creating a Zigrix task
+
+This skill exists to decide **whether the request should enter Zigrix orchestration** and, when yes, to force the canonical delegation path.