@defend-tech/opencode-optima 0.1.47 → 0.1.49

package/Agents_Common.md

@@ -18,7 +18,7 @@
 - `product_manager` may investigate, answer, pre-estimate "a qué huele" small/medium/large plus rough story points, and operate ClickUp dashboards; development requests must be converted into properly routed ClickUp tasks.
 - ClickUp delivery types are `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, and `Respuesta del formulario` unless converted or linked.
 - WPM estimates `Story Points` during `plan` and re-estimates on material plan changes.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and code instead of personal names.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima-provided fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and code instead of personal names.
 - ClickUp status actions: `backlog` ignore, `plan` plan plus remove the PM assignee before assigning `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. After validation, Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
 - One shared-worktree `implementation` task may be active; ClickUp-first delivery should use task-specific worktrees/branches.
 - Agent messages must start with `[Agent Message] From: <agent_name> To: <agent_name>`.

package/Agents_Common.prompt.md

@@ -20,7 +20,7 @@
 - `product_manager` may investigate, answer, pre-estimate "a qué huele" small/medium/large plus rough story points, and operate ClickUp dashboards; development requests must become routed ClickUp tasks.
 - ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted or linked.
 - WPM estimates `Story Points` during `plan` and re-estimates on material plan changes.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and code instead of personal names.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
 - ClickUp-first statuses: `backlog` ignore, `plan` plan plus remove the PM assignee before assigning `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
 - Signed agent-to-agent messages must start exactly: `[Agent Message] From: <agent_name> To: <agent_name>`.
 - Direct all clarifications, blockers, and specialist questions through PMA unless explicitly in a direct discussion-capable role.

package/assets/agents/workflow_product_manager.md

@@ -41,7 +41,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 ## Status Actions
 
 - `backlog`: ignore until prioritized.
-- Human registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role IDs in workflow text, ClickUp comments, and automation config.
+- Human registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if the task worktree lacks that file, use the Optima-provided Human Role Fallback Registry and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role IDs in workflow text, ClickUp comments, and automation config.
 - `plan`: clarify AC/SCR/test strategy with Validator/QA, decompose, create/update Definition, estimate Story Points, hand off implementation, remove PM assignee first, then assign `CTO` + `PO` or next owner; target zero PM-assigned tasks.
 - `in progress`: execute through assigned delivery agent or workflow runner.
 - `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks. Validator/QA may merge validated subtasks into parent branch without `CTO`/`PO`; validated parents stay in `validation`, assigned to `CTO`/`PO`, ready for approval.

package/dist/index.js

@@ -8130,6 +8130,42 @@ function resolveHumanRoles(roles = CLICKUP_FINAL_APPROVER_ROLES, registry = load
 function finalApprovalAssignees(roles = CLICKUP_FINAL_APPROVER_ROLES, registry = loadHumansRegistry()) {
   return resolveHumanRoles(roles, registry);
 }
+function normalizedHumanRoleRegistry(registry = loadHumansRegistry()) {
+  return Object.fromEntries(
+    Object.entries(registry || {}).map(([role, human]) => [String(role || "").trim(), String(human || "").trim()]).filter(([role, human]) => role && human)
+  );
+}
+function normalizeClickUpRoleIds(raw = {}) {
+  const source = isPlainObject(raw) ? raw : {};
+  const entries = Object.entries(source).map(([role, id]) => [String(role || "").trim(), String(id || "").trim()]);
+  return Object.fromEntries(entries.filter(([role, id]) => role && id));
+}
+function buildHumanRoleContext({ roles = CLICKUP_FINAL_APPROVER_ROLES, registry = loadHumansRegistry(), roleIds = {} } = {}) {
+  const normalizedRegistry = normalizedHumanRoleRegistry(registry);
+  const normalizedIds = normalizeClickUpRoleIds(roleIds);
+  return [...new Set(roles.map((role) => String(role || "").trim()).filter(Boolean))].map((role) => ({
+    role,
+    human: normalizedRegistry[role] || "",
+    clickupUserId: normalizedIds[role] || ""
+  }));
+}
+function formatHumanRoleContext(context = []) {
+  const entries = Array.isArray(context) ? context : [];
+  if (!entries.length) return "";
+  return entries.map((entry) => {
+    const human = entry.human ? ` = ${entry.human}` : "";
+    const id = entry.clickupUserId ? ` (ClickUp ID: ${entry.clickupUserId})` : "";
+    return `- ${entry.role}${human}${id}`;
+  }).join("\n");
+}
+function hasActionableClickUpRoute(result = {}) {
+  if (!result?.ok || result.action === "ignored") return false;
+  if (!result.sessionId) return false;
+  if (result.action === "message_delivery_failed" || result.action === "error") return false;
+  if (result.deliveryVerification?.ok === false) return false;
+  if (result.deliveryVerification?.method === "prompt_admission") return false;
+  return true;
+}
 function determineClickUpMergeAuthority({ isSubtask = false, clickupStatus = "", validationPassed = false, mergeFailed = false, finalApprovalRoles = CLICKUP_FINAL_APPROVER_ROLES, humansRegistry } = {}) {
   if (mergeFailed) {
     return {
@@ -9015,7 +9051,8 @@ function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd
       ignoredStatuses,
       metadataFieldId: String(routing.metadata_field_id || routing.metadataFieldId || "").trim(),
       metadataKey: String(routing.metadata_key || routing.metadataKey || CLICKUP_PM_METADATA_KEY).trim(),
-      ignoredCommentAuthorId: String(routing.ignored_comment_author_id || routing.ignoredCommentAuthorId || routing.product_manager_mention_user_id || routing.productManagerMentionUserId || "").trim()
+      ignoredCommentAuthorId: String(routing.ignored_comment_author_id || routing.ignoredCommentAuthorId || routing.product_manager_mention_user_id || routing.productManagerMentionUserId || "").trim(),
+      humanRoleClickUpIds: normalizeClickUpRoleIds(routing.human_role_clickup_ids || routing.humanRoleClickUpIds || routing.role_ids || routing.roleIds)
     }
   };
   const errors = [];
@@ -9619,6 +9656,22 @@ async function createOpenCodeSession(client, { title, directory, agent } = {}) {
   }
   throw firstError || new Error("OpenCode session create failed.");
 }
+async function waitForOpenCodeReadiness(client, { worktree = process.cwd(), attempts = 10, delayMs = 500, now = () => /* @__PURE__ */ new Date() } = {}) {
+  if (typeof client?.session?.create !== "function") return { ok: true, skipped: true, reason: "session_create_probe_unavailable" };
+  let lastError = "opencode_not_ready";
+  const maxAttempts = Math.max(1, Number(attempts) || 1);
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const sessionId = await createOpenCodeSession(client, { title: `Optima startup readiness probe ${now().toISOString()}`, directory: worktree });
+      if (await openCodeSessionExists(client, sessionId)) return { ok: true, method: "session_create_probe", sessionId, attempts: attempt };
+      lastError = "readiness_probe_session_not_visible";
+    } catch (error) {
+      lastError = error.message || "opencode_not_ready";
+    }
+    if (attempt < maxAttempts && delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return { ok: false, reason: lastError, attempts: maxAttempts };
+}
 function assertOpenCodePromptAccepted(result) {
   const status = Number(result?.status || result?.response?.status || result?.error?.status || 0);
   if (status >= 400 || result?.ok === false || result?.error) {
@@ -9656,13 +9709,13 @@ async function readOpenCodeJsonResponse(response, endpointName) {
     return { raw };
   }
 }
-async function sendOpenCodeSessionEventDirect({ baseUrl, sessionId, text, agent, fetchImpl = globalThis.fetch } = {}) {
+async function sendOpenCodeSessionEventDirect({ baseUrl, sessionId, text, agent, fetchImpl = globalThis.fetch, legacyOnly = false } = {}) {
   if (typeof fetchImpl !== "function") throw new Error("OpenCode direct prompt delivery requires fetch.");
   const root = normalizeOpenCodeBaseUrl(baseUrl, "");
   if (!root) throw new Error("OpenCode direct prompt delivery requires a base URL.");
   const encodedSession = encodeURIComponent(sessionId);
   const attempts = [
-    {
+    legacyOnly ? null : {
       name: "v2 prompt",
       url: `${root}/api/session/${encodedSession}/prompt`,
       body: { prompt: { text }, delivery: "queue", resume: true },
@@ -9681,7 +9734,7 @@ async function sendOpenCodeSessionEventDirect({ baseUrl, sessionId, text, agent,
         return { ok: true, method: "http", endpoint: "/session/{sessionID}/prompt_async", status: response.status, data: data?.data || null, response: data };
       }
     }
-  ];
+  ].filter(Boolean);
   let firstError = null;
   for (const attempt of attempts) {
     const response = await fetchImpl(attempt.url, {
@@ -9715,7 +9768,7 @@ async function callOpenCodePromptWithFallbacks(method, sessionId, flatPayload, s
   }
   throw firstError;
 }
-async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, directory, opencodeBaseUrl, baseUrl, fetchImpl, direct = false } = {}) {
+async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, directory, opencodeBaseUrl, baseUrl, fetchImpl, direct = false, legacyOnly = false } = {}) {
   const directBaseUrl = opencodeBaseUrl || baseUrl;
   const parts = [{ type: "text", text }];
   const flatPayload = { directory, agent, parts };
@@ -9739,7 +9792,7 @@ async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, direct
       firstError ??= error;
     }
   }
-  if (directBaseUrl) return sendOpenCodeSessionEventDirect({ baseUrl: directBaseUrl, sessionId, text, agent, fetchImpl });
+  if (directBaseUrl) return sendOpenCodeSessionEventDirect({ baseUrl: directBaseUrl, sessionId, text, agent, fetchImpl, legacyOnly });
   if (firstError) throw firstError;
   throw new Error("OpenCode client does not expose session.prompt or session.promptAsync.");
 }
@@ -9774,18 +9827,20 @@ function openCodeMessageText(message) {
   for (const part of partList) parts.push(part?.text, part?.content);
   return parts.filter((value) => typeof value === "string").join("\n");
 }
-async function verifyOpenCodeSessionEventDelivery(client, { sessionId, beforeMessages = null, expectedText = "", markers = [], attempts = 3, delayMs = 25 } = {}) {
+async function verifyOpenCodeSessionEventDelivery(client, { sessionId, beforeMessages = null, expectedText = "", markers = [], attempts = 8, delayMs = 250 } = {}) {
   let lastError = "message_verification_unavailable";
   for (let attempt = 0; attempt < Math.max(1, attempts); attempt += 1) {
     try {
       const afterMessages = await readOpenCodeSessionMessages(client, { sessionId, limit: 50 });
-      if (!afterMessages) return { ok: true, method: "verification_unavailable", skipped: true };
+      if (!afterMessages) return { ok: false, reason: "message_verification_unavailable" };
       const beforeCount = Array.isArray(beforeMessages) ? beforeMessages.length : null;
-      if (beforeCount !== null && afterMessages.length > beforeCount) return { ok: true, method: "message_count", beforeCount, afterCount: afterMessages.length };
+      const lastMessage = afterMessages.at(-1) || null;
+      const lastMessageId = lastMessage?.id || lastMessage?.messageID || lastMessage?.messageId || null;
+      if (beforeCount !== null && afterMessages.length > beforeCount) return { ok: true, method: "message_count", beforeCount, afterCount: afterMessages.length, lastMessageId };
       const textNeedles = [expectedText, ...markers].map((value) => String(value || "").trim()).filter(Boolean);
       const haystack = afterMessages.slice(-20).map(openCodeMessageText).join("\n");
       const matched = textNeedles.find((needle) => haystack.includes(needle));
-      if (matched) return { ok: true, method: "message_text", marker: matched, beforeCount, afterCount: afterMessages.length };
+      if (matched) return { ok: true, method: "message_text", marker: matched, beforeCount, afterCount: afterMessages.length, lastMessageId };
       lastError = "message_not_visible";
     } catch (error) {
       lastError = error.message || "message_verification_failed";
@@ -9820,21 +9875,28 @@ async function deliverClickUpSessionEventWithVerification({ openCodeClient, send
     const blocker2 = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: error.message, source: "delivery_admission_failed" });
     return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2 };
   }
-  if (admissionVerification) return { ok: true, verification: admissionVerification, fallback: false };
   let verification = await verifySessionEventDelivery(openCodeClient, { sessionId, beforeMessages, expectedText: text, markers: eventMarkers });
-  if (verification?.ok) return { ok: true, verification, fallback: false };
+  if (verification?.ok) return { ok: true, verification, admissionVerification, fallback: false };
+  if (verification?.reason === "message_verification_unavailable" && !admissionVerification) {
+    return { ok: true, verification: { ok: true, method: "legacy_prompt_accepted", skipped: true }, fallback: false };
+  }
+  if (admissionVerification) {
+    appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_admitted_but_invisible", taskId, sessionId, admission: admissionVerification, reason: verification?.reason || "message_not_visible" });
+  }
   const canFallbackDirect = Boolean(opencodeBaseUrl);
   if (canFallbackDirect) {
     const retryBeforeMessages = await readOpenCodeSessionMessages(openCodeClient, { sessionId, limit: 50 }).catch(() => beforeMessages);
-    const retrySendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: true });
+    const retrySendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: true, legacyOnly: Boolean(admissionVerification) });
     try {
       admissionVerification = openCodePromptAdmissionVerification(retrySendResult, sessionId);
     } catch (error) {
       verification = { ok: false, reason: error.message };
     }
-    if (admissionVerification) return { ok: true, verification: admissionVerification, fallback: true };
     verification = await verifySessionEventDelivery(openCodeClient, { sessionId, beforeMessages: retryBeforeMessages, expectedText: text, markers: eventMarkers });
-    if (verification?.ok) return { ok: true, verification, fallback: true };
+    if (verification?.ok) return { ok: true, verification, admissionVerification, fallback: true };
+    if (verification?.reason === "message_verification_unavailable" && !admissionVerification) {
+      return { ok: true, verification: { ok: true, method: "legacy_prompt_accepted", skipped: true }, fallback: true };
+    }
   }
   const reason = verification?.reason || "message_delivery_failed";
   appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason, fallbackAttempted: canFallbackDirect });
@@ -9880,11 +9942,12 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   const replacementMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(metadataWithRouting, config.routing.metadataKey, replacementSessionId), config.routing.metadataKey);
   await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: replacementMetadata });
   appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_succeeded", taskId, staleSessionId, replacementSessionId });
-  return { ok: true, action: "sent_to_replacement_session", taskId, sessionId: replacementSessionId, staleSessionId, replacementAttempted: true, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath, deliveryVerification: replacementDelivery.verification, deliveryFallback: replacementDelivery.fallback };
+  return { ok: true, action: "sent_to_replacement_session", taskId, sessionId: replacementSessionId, staleSessionId, replacementAttempted: true, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath, deliveryVerification: replacementDelivery.verification, deliveryAdmission: replacementDelivery.admissionVerification, deliveryFallback: replacementDelivery.fallback, deliveryAttempts: replacementDelivery.fallback ? 2 : 1 };
 }
-function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", worktree = "", deliveryEvidencePath = "" }) {
+function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", worktree = "", deliveryEvidencePath = "", humanRoleContext = [] }) {
   const comment = clickUpCommentFromPayload(payload);
   const commentText = clickUpCommentText(comment).trim();
+  const humanRoleLines = formatHumanRoleContext(humanRoleContext);
   return [
     "[ClickUp Webhook Event]",
     `Event: ${eventType}`,
@@ -9892,9 +9955,12 @@ function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", w
     branch ? `Branch: ${branch}` : null,
     worktree ? `Worktree: ${worktree}` : null,
     deliveryEvidencePath ? `Delivery evidence path: ${deliveryEvidencePath}` : null,
+    humanRoleLines ? "Human role fallback registry (Optima-provided; non-blocking if repo docs/core/humans.md is missing):" : null,
+    humanRoleLines || null,
     commentText ? `Comment: ${commentText}` : null,
     "",
     "Handle this ClickUp Product Manager event using the ClickUp-first workflow rules. Do not assume broad chat routing; this event passed Optima webhook gates.",
+    "If the task worktree lacks docs/core/humans.md, use the Optima-provided human role fallback registry above instead of blocking solely on that missing file.",
     deliveryEvidencePath ? `Final merge-trackable evidence must be written under ${deliveryEvidencePath}; use .optima only as local mirror/staging.` : null
   ].filter((part) => part !== null).join("\n");
 }
@@ -10145,7 +10211,8 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId)}/SUMMARY.md`
   };
   const metadataWithRouting = setClickUpTaskRoutingMetadata(existingMetadata, routingMetadata);
-  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath });
+  const humanRoleContext = buildHumanRoleContext({ roleIds: config.routing?.humanRoleClickUpIds });
+  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, humanRoleContext });
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
@@ -10171,7 +10238,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
     const { [taskId]: _completedPending, ...remainingPending } = stateToPersist.pendingSessions || {};
     stateToPersist = { ...stateToPersist, pendingSessions: remainingPending };
-    return finish({ ok: true, action: "created_session", taskId, sessionId: pendingSessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryFallback: delivery.fallback });
+    return finish({ ok: true, action: "created_session", taskId, sessionId: pendingSessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryAdmission: delivery.admissionVerification, deliveryFallback: delivery.fallback, deliveryAttempts: delivery.fallback ? 2 : 1 });
   }
   const sessionId = String(existingSessionId);
   if (await sessionExists(openCodeClient, sessionId)) {
@@ -10181,7 +10248,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
       const recovery2 = await recoverClickUpPmSession({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, staleSessionId: sessionId, sessionTitle, taskRoute, metadataWithRouting, config, prompt, eventMarkers: [taskId, eventType], deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, eventKey, createSession, verifySessionEventDelivery });
       return finish(recovery2);
     }
-    return finish({ ok: true, action: "sent_to_existing_session", taskId, sessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryFallback: delivery.fallback });
+    return finish({ ok: true, action: "sent_to_existing_session", taskId, sessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryAdmission: delivery.admissionVerification, deliveryFallback: delivery.fallback, deliveryAttempts: delivery.fallback ? 2 : 1 });
   }
   const at = now().toISOString();
   appendClickUpWebhookLocalLog(worktree, { type: "missing_session", taskId, sessionId, host, at });
@@ -10192,8 +10259,11 @@ async function routeClickUpWebhookEvent(options = {}) {
   const taskId = clickUpTaskIdFromPayload(options.payload || {});
   return withClickUpTaskRouteLock(taskId, () => routeClickUpWebhookEventUnlocked(options));
 }
-async function reconcileClickUpStartup({ config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, saveState = null, now = () => /* @__PURE__ */ new Date(), limit = CLICKUP_WEBHOOK_STARTUP_TASK_LIMIT } = {}) {
+async function reconcileClickUpStartup({ config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery, waitForReadiness = waitForOpenCodeReadiness, saveState = null, now = () => /* @__PURE__ */ new Date(), limit = CLICKUP_WEBHOOK_STARTUP_TASK_LIMIT } = {}) {
   if (!config || !clickupClient?.listAssignedTasks) return { ok: true, skipped: true, reason: "clickup_task_listing_unavailable", assigned: 0, comments: 0 };
+  const readiness = await waitForReadiness(openCodeClient, { worktree, now });
+  appendClickUpWebhookLocalLog(worktree, { type: readiness.ok ? "startup_reconciliation_readiness_ready" : "startup_reconciliation_readiness_failed", ...readiness });
+  if (!readiness.ok) return { ok: false, skipped: true, reason: "opencode_not_ready", readiness, assigned: 0, comments: 0, ignored: 0, errors: 1, undelivered: 1, tasks: [], validation: { undelivered: 1, emptyPromptSessions: [] } };
   let authorizedUserId = "";
   if (clickupClient?.getAuthorizedUser) {
     try {
@@ -10210,7 +10280,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
   };
   const lastWebhookMs = clickUpTimestampMs(mutableState.lastWebhookAt);
   const ignored = new Set((config.routing?.ignoredStatuses || CLICKUP_WEBHOOK_TERMINAL_STATUSES).map(normalizeClickUpStatus));
-  const routed = { assigned: 0, comments: 0, ignored: 0, errors: 0 };
+  const routed = { assigned: 0, comments: 0, ignored: 0, errors: 0, undelivered: 0, tasks: [] };
   clickUpWebhookLifecycleLog(worktree, { type: "startup_reconciliation_started", lastWebhookAt: state.lastWebhookAt || null });
   const listed = await clickupClient.listAssignedTasks({ assigneeId: config.routing.productManagerAssigneeId, limit });
   const tasks = clickUpTaskListItems(listed).slice(0, limit);
@@ -10239,18 +10309,44 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
         sessionExists,
         createSession,
         sendSessionEvent,
+        verifySessionEventDelivery,
         saveState: persistState,
         now
       });
-      if (result?.ok && result.action !== "ignored") {
+      const routeSummary = {
+        taskId,
+        action: result?.action || "unknown",
+        ok: result?.ok === true,
+        sessionId: result?.sessionId || result?.replacementSessionId || null,
+        branch: result?.branch || null,
+        worktree: result?.worktree || null,
+        verification: result?.deliveryVerification?.method || result?.deliveryVerification?.reason || null,
+        delivered: hasActionableClickUpRoute(result),
+        attempts: result?.deliveryAttempts || null,
+        finalMessageCount: result?.deliveryVerification?.afterCount ?? null,
+        finalMessageId: result?.deliveryVerification?.lastMessageId || null
+      };
+      routed.tasks.push(routeSummary);
+      appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_routed", ...routeSummary });
+      if (routeSummary.delivered) {
         routed.assigned += 1;
+      } else if (result?.ok && result.action === "ignored") {
+        routed.ignored += 1;
       } else if (result?.ok === false) {
         routed.errors += 1;
+        routed.undelivered += 1;
+        appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: result?.action || "error", sessionId: routeSummary.sessionId, reason: result.reason || "startup_reconciliation_route_failed" });
         if (!result.blockerTag) await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: result.reason || "startup_reconciliation_route_failed", source: "startup_reconciliation_task" });
+      } else {
+        routed.undelivered += 1;
+        appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: routeSummary.action, sessionId: routeSummary.sessionId, reason: "route_not_actionable" });
       }
     } catch (error) {
       routed.errors += 1;
+      routed.undelivered += 1;
+      routed.tasks.push({ taskId, action: "error", ok: false, sessionId: null, branch: null, worktree: null, verification: error.message, delivered: false });
       appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_failed", taskId, message: error.message });
+      appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: "error", sessionId: null, reason: "startup_reconciliation_task_failed" });
       await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "startup_reconciliation_task_failed", source: "startup_reconciliation_task" });
     }
     if (!lastWebhookMs || !clickupClient?.getTaskComments) continue;
@@ -10273,6 +10369,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
           sessionExists,
           createSession,
           sendSessionEvent,
+          verifySessionEventDelivery,
           saveState: persistState,
           now
         });
@@ -10284,8 +10381,12 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
       await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "startup_reconciliation_comments_failed", source: "startup_reconciliation_comments" });
     }
   }
+  const emptyPromptSessions = routed.tasks.filter((task) => task.delivered === false && task.sessionId);
+  if (emptyPromptSessions.length > 0) {
+    appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_validation_failed", tasks: emptyPromptSessions });
+  }
   clickUpWebhookLifecycleLog(worktree, { type: "startup_reconciliation_finished", ...routed });
-  return { ok: routed.errors === 0, ...routed };
+  return { ok: routed.errors === 0 && routed.undelivered === 0, ...routed, validation: { undelivered: routed.undelivered, emptyPromptSessions } };
 }
 function clickUpWebhookExpectedPath(config) {
   try {
@@ -11403,6 +11504,19 @@ ${additionFragment}`;
         delete agentConfig.tools.optima_prompt_workflow;
       }
     }
+    if (id === "workflow_product_manager") {
+      const humanRoleContext = buildHumanRoleContext({ roleIds: options.clickUpWebhookValidation?.config?.routing?.humanRoleClickUpIds });
+      const humanRoleLines = formatHumanRoleContext(humanRoleContext);
+      if (humanRoleLines) {
+        agentConfig.prompt = `${agentConfig.prompt}
+
+## Optima Human Role Fallback Registry
+
+${humanRoleLines}
+
+Use this Optima-provided fallback when the current task worktree lacks docs/core/humans.md; missing repo-local humans.md is not a hard blocker when this context or configured ClickUp IDs are present.`;
+      }
+    }
     ourAgents[id] = agentConfig;
     if (repoCfg.features?.debug_dumps !== false) {
       const debugPath = path2.join(debugDir, `${id}.md`);
@@ -12071,7 +12185,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionMessages, reconcileClickUpStartup, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionMessages, reconcileClickUpStartup, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 export {
   OptimaPlugin as default
 };

package/dist/sanitize_cli.js

@@ -8137,6 +8137,42 @@ function resolveHumanRoles(roles = CLICKUP_FINAL_APPROVER_ROLES, registry = load
 function finalApprovalAssignees(roles = CLICKUP_FINAL_APPROVER_ROLES, registry = loadHumansRegistry()) {
   return resolveHumanRoles(roles, registry);
 }
+function normalizedHumanRoleRegistry(registry = loadHumansRegistry()) {
+  return Object.fromEntries(
+    Object.entries(registry || {}).map(([role, human]) => [String(role || "").trim(), String(human || "").trim()]).filter(([role, human]) => role && human)
+  );
+}
+function normalizeClickUpRoleIds(raw = {}) {
+  const source = isPlainObject(raw) ? raw : {};
+  const entries = Object.entries(source).map(([role, id]) => [String(role || "").trim(), String(id || "").trim()]);
+  return Object.fromEntries(entries.filter(([role, id]) => role && id));
+}
+function buildHumanRoleContext({ roles = CLICKUP_FINAL_APPROVER_ROLES, registry = loadHumansRegistry(), roleIds = {} } = {}) {
+  const normalizedRegistry = normalizedHumanRoleRegistry(registry);
+  const normalizedIds = normalizeClickUpRoleIds(roleIds);
+  return [...new Set(roles.map((role) => String(role || "").trim()).filter(Boolean))].map((role) => ({
+    role,
+    human: normalizedRegistry[role] || "",
+    clickupUserId: normalizedIds[role] || ""
+  }));
+}
+function formatHumanRoleContext(context = []) {
+  const entries = Array.isArray(context) ? context : [];
+  if (!entries.length) return "";
+  return entries.map((entry) => {
+    const human = entry.human ? ` = ${entry.human}` : "";
+    const id = entry.clickupUserId ? ` (ClickUp ID: ${entry.clickupUserId})` : "";
+    return `- ${entry.role}${human}${id}`;
+  }).join("\n");
+}
+function hasActionableClickUpRoute(result = {}) {
+  if (!result?.ok || result.action === "ignored") return false;
+  if (!result.sessionId) return false;
+  if (result.action === "message_delivery_failed" || result.action === "error") return false;
+  if (result.deliveryVerification?.ok === false) return false;
+  if (result.deliveryVerification?.method === "prompt_admission") return false;
+  return true;
+}
 function determineClickUpMergeAuthority({ isSubtask = false, clickupStatus = "", validationPassed = false, mergeFailed = false, finalApprovalRoles = CLICKUP_FINAL_APPROVER_ROLES, humansRegistry } = {}) {
   if (mergeFailed) {
     return {
@@ -9022,7 +9058,8 @@ function normalizeClickUpWebhookConfig(rawClickUp = null, worktree = process.cwd
       ignoredStatuses,
       metadataFieldId: String(routing.metadata_field_id || routing.metadataFieldId || "").trim(),
       metadataKey: String(routing.metadata_key || routing.metadataKey || CLICKUP_PM_METADATA_KEY).trim(),
-      ignoredCommentAuthorId: String(routing.ignored_comment_author_id || routing.ignoredCommentAuthorId || routing.product_manager_mention_user_id || routing.productManagerMentionUserId || "").trim()
+      ignoredCommentAuthorId: String(routing.ignored_comment_author_id || routing.ignoredCommentAuthorId || routing.product_manager_mention_user_id || routing.productManagerMentionUserId || "").trim(),
+      humanRoleClickUpIds: normalizeClickUpRoleIds(routing.human_role_clickup_ids || routing.humanRoleClickUpIds || routing.role_ids || routing.roleIds)
     }
   };
   const errors = [];
@@ -9626,6 +9663,22 @@ async function createOpenCodeSession(client, { title, directory, agent } = {}) {
   }
   throw firstError || new Error("OpenCode session create failed.");
 }
+async function waitForOpenCodeReadiness(client, { worktree = process.cwd(), attempts = 10, delayMs = 500, now = () => /* @__PURE__ */ new Date() } = {}) {
+  if (typeof client?.session?.create !== "function") return { ok: true, skipped: true, reason: "session_create_probe_unavailable" };
+  let lastError = "opencode_not_ready";
+  const maxAttempts = Math.max(1, Number(attempts) || 1);
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    try {
+      const sessionId = await createOpenCodeSession(client, { title: `Optima startup readiness probe ${now().toISOString()}`, directory: worktree });
+      if (await openCodeSessionExists(client, sessionId)) return { ok: true, method: "session_create_probe", sessionId, attempts: attempt };
+      lastError = "readiness_probe_session_not_visible";
+    } catch (error) {
+      lastError = error.message || "opencode_not_ready";
+    }
+    if (attempt < maxAttempts && delayMs > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+  }
+  return { ok: false, reason: lastError, attempts: maxAttempts };
+}
 function assertOpenCodePromptAccepted(result) {
   const status = Number(result?.status || result?.response?.status || result?.error?.status || 0);
   if (status >= 400 || result?.ok === false || result?.error) {
@@ -9663,13 +9716,13 @@ async function readOpenCodeJsonResponse(response, endpointName) {
     return { raw };
   }
 }
-async function sendOpenCodeSessionEventDirect({ baseUrl, sessionId, text, agent, fetchImpl = globalThis.fetch } = {}) {
+async function sendOpenCodeSessionEventDirect({ baseUrl, sessionId, text, agent, fetchImpl = globalThis.fetch, legacyOnly = false } = {}) {
   if (typeof fetchImpl !== "function") throw new Error("OpenCode direct prompt delivery requires fetch.");
   const root = normalizeOpenCodeBaseUrl(baseUrl, "");
   if (!root) throw new Error("OpenCode direct prompt delivery requires a base URL.");
   const encodedSession = encodeURIComponent(sessionId);
   const attempts = [
-    {
+    legacyOnly ? null : {
       name: "v2 prompt",
       url: `${root}/api/session/${encodedSession}/prompt`,
       body: { prompt: { text }, delivery: "queue", resume: true },
@@ -9688,7 +9741,7 @@ async function sendOpenCodeSessionEventDirect({ baseUrl, sessionId, text, agent,
         return { ok: true, method: "http", endpoint: "/session/{sessionID}/prompt_async", status: response.status, data: data?.data || null, response: data };
       }
     }
-  ];
+  ].filter(Boolean);
   let firstError = null;
   for (const attempt of attempts) {
     const response = await fetchImpl(attempt.url, {
@@ -9722,7 +9775,7 @@ async function callOpenCodePromptWithFallbacks(method, sessionId, flatPayload, s
   }
   throw firstError;
 }
-async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, directory, opencodeBaseUrl, baseUrl, fetchImpl, direct = false } = {}) {
+async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, directory, opencodeBaseUrl, baseUrl, fetchImpl, direct = false, legacyOnly = false } = {}) {
   const directBaseUrl = opencodeBaseUrl || baseUrl;
   const parts = [{ type: "text", text }];
   const flatPayload = { directory, agent, parts };
@@ -9746,7 +9799,7 @@ async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, direct
       firstError ??= error;
     }
   }
-  if (directBaseUrl) return sendOpenCodeSessionEventDirect({ baseUrl: directBaseUrl, sessionId, text, agent, fetchImpl });
+  if (directBaseUrl) return sendOpenCodeSessionEventDirect({ baseUrl: directBaseUrl, sessionId, text, agent, fetchImpl, legacyOnly });
   if (firstError) throw firstError;
   throw new Error("OpenCode client does not expose session.prompt or session.promptAsync.");
 }
@@ -9781,18 +9834,20 @@ function openCodeMessageText(message) {
   for (const part of partList) parts.push(part?.text, part?.content);
   return parts.filter((value) => typeof value === "string").join("\n");
 }
-async function verifyOpenCodeSessionEventDelivery(client, { sessionId, beforeMessages = null, expectedText = "", markers = [], attempts = 3, delayMs = 25 } = {}) {
+async function verifyOpenCodeSessionEventDelivery(client, { sessionId, beforeMessages = null, expectedText = "", markers = [], attempts = 8, delayMs = 250 } = {}) {
   let lastError = "message_verification_unavailable";
   for (let attempt = 0; attempt < Math.max(1, attempts); attempt += 1) {
     try {
       const afterMessages = await readOpenCodeSessionMessages(client, { sessionId, limit: 50 });
-      if (!afterMessages) return { ok: true, method: "verification_unavailable", skipped: true };
+      if (!afterMessages) return { ok: false, reason: "message_verification_unavailable" };
       const beforeCount = Array.isArray(beforeMessages) ? beforeMessages.length : null;
-      if (beforeCount !== null && afterMessages.length > beforeCount) return { ok: true, method: "message_count", beforeCount, afterCount: afterMessages.length };
+      const lastMessage = afterMessages.at(-1) || null;
+      const lastMessageId = lastMessage?.id || lastMessage?.messageID || lastMessage?.messageId || null;
+      if (beforeCount !== null && afterMessages.length > beforeCount) return { ok: true, method: "message_count", beforeCount, afterCount: afterMessages.length, lastMessageId };
       const textNeedles = [expectedText, ...markers].map((value) => String(value || "").trim()).filter(Boolean);
       const haystack = afterMessages.slice(-20).map(openCodeMessageText).join("\n");
       const matched = textNeedles.find((needle) => haystack.includes(needle));
-      if (matched) return { ok: true, method: "message_text", marker: matched, beforeCount, afterCount: afterMessages.length };
+      if (matched) return { ok: true, method: "message_text", marker: matched, beforeCount, afterCount: afterMessages.length, lastMessageId };
       lastError = "message_not_visible";
     } catch (error) {
       lastError = error.message || "message_verification_failed";
@@ -9827,21 +9882,28 @@ async function deliverClickUpSessionEventWithVerification({ openCodeClient, send
     const blocker2 = await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: error.message, source: "delivery_admission_failed" });
     return { ok: false, action: "message_delivery_failed", reason: error.message, taskId, sessionId, fallbackAttempted: false, blockerTag: blocker2 };
   }
-  if (admissionVerification) return { ok: true, verification: admissionVerification, fallback: false };
   let verification = await verifySessionEventDelivery(openCodeClient, { sessionId, beforeMessages, expectedText: text, markers: eventMarkers });
-  if (verification?.ok) return { ok: true, verification, fallback: false };
+  if (verification?.ok) return { ok: true, verification, admissionVerification, fallback: false };
+  if (verification?.reason === "message_verification_unavailable" && !admissionVerification) {
+    return { ok: true, verification: { ok: true, method: "legacy_prompt_accepted", skipped: true }, fallback: false };
+  }
+  if (admissionVerification) {
+    appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_admitted_but_invisible", taskId, sessionId, admission: admissionVerification, reason: verification?.reason || "message_not_visible" });
+  }
   const canFallbackDirect = Boolean(opencodeBaseUrl);
   if (canFallbackDirect) {
     const retryBeforeMessages = await readOpenCodeSessionMessages(openCodeClient, { sessionId, limit: 50 }).catch(() => beforeMessages);
-    const retrySendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: true });
+    const retrySendResult = await sendSessionEvent(openCodeClient, { sessionId, agent, text, directory, opencodeBaseUrl, direct: true, legacyOnly: Boolean(admissionVerification) });
     try {
       admissionVerification = openCodePromptAdmissionVerification(retrySendResult, sessionId);
     } catch (error) {
       verification = { ok: false, reason: error.message };
     }
-    if (admissionVerification) return { ok: true, verification: admissionVerification, fallback: true };
     verification = await verifySessionEventDelivery(openCodeClient, { sessionId, beforeMessages: retryBeforeMessages, expectedText: text, markers: eventMarkers });
-    if (verification?.ok) return { ok: true, verification, fallback: true };
+    if (verification?.ok) return { ok: true, verification, admissionVerification, fallback: true };
+    if (verification?.reason === "message_verification_unavailable" && !admissionVerification) {
+      return { ok: true, verification: { ok: true, method: "legacy_prompt_accepted", skipped: true }, fallback: true };
+    }
   }
   const reason = verification?.reason || "message_delivery_failed";
   appendClickUpWebhookLocalLog(worktree, { type: "message_delivery_failed", taskId, sessionId, reason, fallbackAttempted: canFallbackDirect });
@@ -9887,11 +9949,12 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   const replacementMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(metadataWithRouting, config.routing.metadataKey, replacementSessionId), config.routing.metadataKey);
   await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: replacementMetadata });
   appendClickUpWebhookLocalLog(worktree, { type: "pm_session_recovery_succeeded", taskId, staleSessionId, replacementSessionId });
-  return { ok: true, action: "sent_to_replacement_session", taskId, sessionId: replacementSessionId, staleSessionId, replacementAttempted: true, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath, deliveryVerification: replacementDelivery.verification, deliveryFallback: replacementDelivery.fallback };
+  return { ok: true, action: "sent_to_replacement_session", taskId, sessionId: replacementSessionId, staleSessionId, replacementAttempted: true, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath, deliveryVerification: replacementDelivery.verification, deliveryAdmission: replacementDelivery.admissionVerification, deliveryFallback: replacementDelivery.fallback, deliveryAttempts: replacementDelivery.fallback ? 2 : 1 };
 }
-function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", worktree = "", deliveryEvidencePath = "" }) {
+function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", worktree = "", deliveryEvidencePath = "", humanRoleContext = [] }) {
   const comment = clickUpCommentFromPayload(payload);
   const commentText = clickUpCommentText(comment).trim();
+  const humanRoleLines = formatHumanRoleContext(humanRoleContext);
   return [
     "[ClickUp Webhook Event]",
     `Event: ${eventType}`,
@@ -9899,9 +9962,12 @@ function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", w
     branch ? `Branch: ${branch}` : null,
     worktree ? `Worktree: ${worktree}` : null,
     deliveryEvidencePath ? `Delivery evidence path: ${deliveryEvidencePath}` : null,
+    humanRoleLines ? "Human role fallback registry (Optima-provided; non-blocking if repo docs/core/humans.md is missing):" : null,
+    humanRoleLines || null,
     commentText ? `Comment: ${commentText}` : null,
     "",
     "Handle this ClickUp Product Manager event using the ClickUp-first workflow rules. Do not assume broad chat routing; this event passed Optima webhook gates.",
+    "If the task worktree lacks docs/core/humans.md, use the Optima-provided human role fallback registry above instead of blocking solely on that missing file.",
     deliveryEvidencePath ? `Final merge-trackable evidence must be written under ${deliveryEvidencePath}; use .optima only as local mirror/staging.` : null
   ].filter((part) => part !== null).join("\n");
 }
@@ -10152,7 +10218,8 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId)}/SUMMARY.md`
   };
   const metadataWithRouting = setClickUpTaskRoutingMetadata(existingMetadata, routingMetadata);
-  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath });
+  const humanRoleContext = buildHumanRoleContext({ roleIds: config.routing?.humanRoleClickUpIds });
+  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, humanRoleContext });
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
@@ -10178,7 +10245,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
     const { [taskId]: _completedPending, ...remainingPending } = stateToPersist.pendingSessions || {};
     stateToPersist = { ...stateToPersist, pendingSessions: remainingPending };
-    return finish({ ok: true, action: "created_session", taskId, sessionId: pendingSessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryFallback: delivery.fallback });
+    return finish({ ok: true, action: "created_session", taskId, sessionId: pendingSessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryAdmission: delivery.admissionVerification, deliveryFallback: delivery.fallback, deliveryAttempts: delivery.fallback ? 2 : 1 });
   }
   const sessionId = String(existingSessionId);
   if (await sessionExists(openCodeClient, sessionId)) {
@@ -10188,7 +10255,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
       const recovery2 = await recoverClickUpPmSession({ openCodeClient, sendSessionEvent, clickupClient, worktree, taskId, staleSessionId: sessionId, sessionTitle, taskRoute, metadataWithRouting, config, prompt, eventMarkers: [taskId, eventType], deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, eventKey, createSession, verifySessionEventDelivery });
       return finish(recovery2);
     }
-    return finish({ ok: true, action: "sent_to_existing_session", taskId, sessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryFallback: delivery.fallback });
+    return finish({ ok: true, action: "sent_to_existing_session", taskId, sessionId, eventKey, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath, evidencePath: routingMetadata.evidence_path, deliveryVerification: delivery.verification, deliveryAdmission: delivery.admissionVerification, deliveryFallback: delivery.fallback, deliveryAttempts: delivery.fallback ? 2 : 1 });
   }
   const at = now().toISOString();
   appendClickUpWebhookLocalLog(worktree, { type: "missing_session", taskId, sessionId, host, at });
@@ -10199,8 +10266,11 @@ async function routeClickUpWebhookEvent(options = {}) {
   const taskId = clickUpTaskIdFromPayload(options.payload || {});
   return withClickUpTaskRouteLock(taskId, () => routeClickUpWebhookEventUnlocked(options));
 }
-async function reconcileClickUpStartup({ config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, saveState = null, now = () => /* @__PURE__ */ new Date(), limit = CLICKUP_WEBHOOK_STARTUP_TASK_LIMIT } = {}) {
+async function reconcileClickUpStartup({ config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery, waitForReadiness = waitForOpenCodeReadiness, saveState = null, now = () => /* @__PURE__ */ new Date(), limit = CLICKUP_WEBHOOK_STARTUP_TASK_LIMIT } = {}) {
   if (!config || !clickupClient?.listAssignedTasks) return { ok: true, skipped: true, reason: "clickup_task_listing_unavailable", assigned: 0, comments: 0 };
+  const readiness = await waitForReadiness(openCodeClient, { worktree, now });
+  appendClickUpWebhookLocalLog(worktree, { type: readiness.ok ? "startup_reconciliation_readiness_ready" : "startup_reconciliation_readiness_failed", ...readiness });
+  if (!readiness.ok) return { ok: false, skipped: true, reason: "opencode_not_ready", readiness, assigned: 0, comments: 0, ignored: 0, errors: 1, undelivered: 1, tasks: [], validation: { undelivered: 1, emptyPromptSessions: [] } };
   let authorizedUserId = "";
   if (clickupClient?.getAuthorizedUser) {
     try {
@@ -10217,7 +10287,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
   };
   const lastWebhookMs = clickUpTimestampMs(mutableState.lastWebhookAt);
   const ignored = new Set((config.routing?.ignoredStatuses || CLICKUP_WEBHOOK_TERMINAL_STATUSES).map(normalizeClickUpStatus));
-  const routed = { assigned: 0, comments: 0, ignored: 0, errors: 0 };
+  const routed = { assigned: 0, comments: 0, ignored: 0, errors: 0, undelivered: 0, tasks: [] };
   clickUpWebhookLifecycleLog(worktree, { type: "startup_reconciliation_started", lastWebhookAt: state.lastWebhookAt || null });
   const listed = await clickupClient.listAssignedTasks({ assigneeId: config.routing.productManagerAssigneeId, limit });
   const tasks = clickUpTaskListItems(listed).slice(0, limit);
@@ -10246,18 +10316,44 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
         sessionExists,
         createSession,
         sendSessionEvent,
+        verifySessionEventDelivery,
         saveState: persistState,
         now
       });
-      if (result?.ok && result.action !== "ignored") {
+      const routeSummary = {
+        taskId,
+        action: result?.action || "unknown",
+        ok: result?.ok === true,
+        sessionId: result?.sessionId || result?.replacementSessionId || null,
+        branch: result?.branch || null,
+        worktree: result?.worktree || null,
+        verification: result?.deliveryVerification?.method || result?.deliveryVerification?.reason || null,
+        delivered: hasActionableClickUpRoute(result),
+        attempts: result?.deliveryAttempts || null,
+        finalMessageCount: result?.deliveryVerification?.afterCount ?? null,
+        finalMessageId: result?.deliveryVerification?.lastMessageId || null
+      };
+      routed.tasks.push(routeSummary);
+      appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_routed", ...routeSummary });
+      if (routeSummary.delivered) {
         routed.assigned += 1;
+      } else if (result?.ok && result.action === "ignored") {
+        routed.ignored += 1;
       } else if (result?.ok === false) {
         routed.errors += 1;
+        routed.undelivered += 1;
+        appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: result?.action || "error", sessionId: routeSummary.sessionId, reason: result.reason || "startup_reconciliation_route_failed" });
         if (!result.blockerTag) await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: result.reason || "startup_reconciliation_route_failed", source: "startup_reconciliation_task" });
+      } else {
+        routed.undelivered += 1;
+        appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: routeSummary.action, sessionId: routeSummary.sessionId, reason: "route_not_actionable" });
       }
     } catch (error) {
       routed.errors += 1;
+      routed.undelivered += 1;
+      routed.tasks.push({ taskId, action: "error", ok: false, sessionId: null, branch: null, worktree: null, verification: error.message, delivered: false });
       appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_failed", taskId, message: error.message });
+      appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_task_undelivered", taskId, action: "error", sessionId: null, reason: "startup_reconciliation_task_failed" });
       await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "startup_reconciliation_task_failed", source: "startup_reconciliation_task" });
     }
     if (!lastWebhookMs || !clickupClient?.getTaskComments) continue;
@@ -10280,6 +10376,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
           sessionExists,
           createSession,
           sendSessionEvent,
+          verifySessionEventDelivery,
           saveState: persistState,
           now
         });
@@ -10291,8 +10388,12 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
       await applyClickUpBlockerTag({ clickupClient, worktree, taskId, reason: "startup_reconciliation_comments_failed", source: "startup_reconciliation_comments" });
     }
   }
+  const emptyPromptSessions = routed.tasks.filter((task) => task.delivered === false && task.sessionId);
+  if (emptyPromptSessions.length > 0) {
+    appendClickUpWebhookLocalLog(worktree, { type: "startup_reconciliation_validation_failed", tasks: emptyPromptSessions });
+  }
   clickUpWebhookLifecycleLog(worktree, { type: "startup_reconciliation_finished", ...routed });
-  return { ok: routed.errors === 0, ...routed };
+  return { ok: routed.errors === 0 && routed.undelivered === 0, ...routed, validation: { undelivered: routed.undelivered, emptyPromptSessions } };
 }
 function clickUpWebhookExpectedPath(config) {
   try {
@@ -11410,6 +11511,19 @@ ${additionFragment}`;
         delete agentConfig.tools.optima_prompt_workflow;
       }
     }
+    if (id === "workflow_product_manager") {
+      const humanRoleContext = buildHumanRoleContext({ roleIds: options.clickUpWebhookValidation?.config?.routing?.humanRoleClickUpIds });
+      const humanRoleLines = formatHumanRoleContext(humanRoleContext);
+      if (humanRoleLines) {
+        agentConfig.prompt = `${agentConfig.prompt}
+
+## Optima Human Role Fallback Registry
+
+${humanRoleLines}
+
+Use this Optima-provided fallback when the current task worktree lacks docs/core/humans.md; missing repo-local humans.md is not a hard blocker when this context or configured ClickUp IDs are present.`;
+      }
+    }
     ourAgents[id] = agentConfig;
     if (repoCfg.features?.debug_dumps !== false) {
       const debugPath = path2.join(debugDir, `${id}.md`);
@@ -12078,7 +12192,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionMessages, reconcileClickUpStartup, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, createOpenCodeSession, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionMessages, reconcileClickUpStartup, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 
 // src/sanitize_cli.js
 var { migrateLegacyOptimaLayout: migrateLegacyOptimaLayout2 } = OptimaPlugin.__internals;

package/docs/core/agent_orchestration.md

@@ -21,7 +21,7 @@
 
 - `product_manager` may answer, investigate, operate dashboards, and pre-estimate "a qué huele" small/medium/large plus rough story points; WPM owns delivery routing.
 - Supported delivery task types are `Tarea`, `Bug`, `Doc`, and `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, and `Respuesta del formulario` unless converted or linked to delivery work.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use the Optima-provided human role fallback context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
 - Status actions are deterministic: `backlog` ignore, `plan` plan plus `Story Points`, test strategy, `Definition`, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead and Validator/QA gates, `merge` parent approval state after `CTO`/`PO` move a validated parent task there, and `completed`/`Closed` ignore unless reopened.
 - Store ClickUp `agent_metadata` JSON with session IDs per agent/type/task/subtask; keep `Definition` as the plan contract and final Documentation as delivered behavior docs.
 - `workflow_product_manager` is registered only when explicit ClickUp webhook mode is configured and the local webhook subscription state is active/valid.

package/docs/core/agent_orchestration.prompt.md

@@ -13,7 +13,7 @@
 - Routing comes from `docs/core/task_model.md`: `tiny` lightweight, `standard` bounded, `complex` decomposed; full mode supports all, mini mode refuses complex.
 - `product_manager` may answer/investigate/dashboard/pre-estimate "a qué huele" plus rough story points; development asks become routed ClickUp tasks.
 - ClickUp-first types: execute `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima-provided fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
 - ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, test strategy, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead + Validator/QA gates; Validator/QA may merge validated subtasks directly into the parent branch; validated parents stay in `validation` for `CTO`/`PO` approval; `merge` means `CTO`/`PO` approved the parent and Validator/QA may attempt parent merge into `dev`; `completed`/`Closed` ignore unless reopened.
 - Shared-worktree rule: one active `implementation` task at a time; isolated `investigation`/`spec` may run in parallel if non-conflicting.
 - Git rules: principal workspace stays on `dev`, never `main`; parent task pulls remote once at start; subtasks trust parent local branch; PoC branches stay `poc/<clickup-task-id>`; subtasks PR to parent branch, parents PR to `dev`, releases PR `dev` -> `main`; failed/conflicted subtask or parent merges return the affected item to `in progress` for the coding owner; no direct `main` pushes.

package/docs/core/role_contracts.md

@@ -20,7 +20,7 @@
 - Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs must be posted to linked ClickUp task/subtask comments or fields.
 - Raw logs stay in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
 - WPM owns ClickUp `Story Points` during `plan`, re-estimation on material plan changes, `agent_metadata` session JSON, `Definition` plan-contract linking, and parent approval routing after validation.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima-provided fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
 - Subtask merge authority belongs to Validator/QA after successful subtask validation: subtask PRs target and merge into the parent branch/workspace without `CTO`/`PO` approval.
 - Parent merge authority is split: after Tech Lead and Validator/QA pass, WPM/Validator assigns `CTO` and `PO` while the parent task remains in `validation`; `CTO`/`PO` approve by moving the parent task to `merge`; Validator/QA then attempts the parent PR merge into `dev`.
 - If a subtask or parent merge conflicts or fails, Validator/QA returns the affected ClickUp task/subtask to `in progress` and routes it back to the coding owner.

package/docs/core/role_contracts.prompt.md

@@ -14,7 +14,7 @@
 - Sync human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs to linked ClickUp task/subtask comments or fields.
 - Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never wholesale raw logs.
 - WPM owns `Story Points` during `plan`, re-estimation on material plan changes, `agent_metadata`, `Definition` plan-contract linking, and parent approval routing after validation.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
 - Validator/QA may merge validated subtask PRs into the parent branch/workspace without `CTO`/`PO` approval.
 - Parent merge authority requires `CTO`/`PO` approval: after Tech Lead + Validator/QA pass, assign both roles while the parent stays in `validation`; they approve by moving it to `merge`; Validator/QA then attempts the parent PR merge into `dev`.
 - Failed or conflicted subtask/parent merges return the affected ClickUp item to `in progress` for the coding owner.

package/docs/core/task_model.md

@@ -11,7 +11,7 @@
 - Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`.
 - Ignored task types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted or linked to delivery work; `Idea` is non-delivery.
 - `product_manager` may pre-estimate "a qué huele" small/medium/large plus rough story points, but development requests must be converted to routed ClickUp work.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
 - Status-to-action mapping: `backlog` -> `ignore`, `plan` -> `plan`, `in progress` -> `execute`, `validation` -> `validate`, `merge` -> `merge`, `completed`/`Closed` -> `ignore` unless reopened. For parent tasks, `merge` means `CTO`/`PO` have approved by moving the task out of `validation`; for subtasks, Validator/QA may merge after successful validation without waiting for `merge` human approval.
 - Branch-safe type slugs are lowercase ASCII: `tarea`, `bug`, `doc`, `poc`.
 

package/docs/core/task_model.prompt.md

@@ -6,7 +6,7 @@
 - Slices: `foundation`, `core`, `logic`, `ui`, `polish`, `qa`, `docs`.
 - ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignored types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
 - Product Manager without workflow never develops; it may pre-estimate "a qué huele" small/medium/large plus rough story points and route development into ClickUp tasks.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
 - ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, test strategy, and `CTO`/`PO` assignment, `in progress` execute, `validation` split Tech Lead + Validator/QA; validated subtasks may be merged by Validator/QA into the parent branch without human approval; validated parent tasks assign `CTO`/`PO` and wait for them to move the task to `merge`; `merge` lets Validator/QA attempt parent PR merge into `dev`; `completed`/`Closed` ignore unless reopened.
 - Routing: keep `tiny` to one slice and usually one specialist; keep `standard` bounded; decompose `complex` into slice-based subtasks.
 - `complex + implementation` normally uses `workflow_runner` in full mode.

package/docs/core/testing_strategy.md

@@ -18,7 +18,7 @@ We adhere to a strict test pyramid strategy to ensure 100% reliability.
 - **Planning Participation:** Validator/QA participates during `plan` for test strategy, required new coverage, Playwright needs, regression scope, and documentation-validation expectations.
 - **Regression:** A full regression suite must be run by the Developer before handing over for technical review.
 - **Split Validation:** Tech Lead reviews architecture, code, PR readiness, standards, and repo-skill use; Validator/QA verifies tests, Playwright flows, regression, required coverage, evidence, and final documentation freshness.
-- **Human Role Registry:** Resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and automation config.
+- **Human Role Registry:** Resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
 - **Merge Execution Gate:** Validator/QA may merge validated subtask PRs into the parent branch/workspace without human approval. Parent PRs to `dev` require Tech Lead and Validator/QA pass plus `CTO`/`PO` approval by moving the parent task to `merge` before Validator/QA attempts the merge. Any conflicted or failed merge returns the affected task/subtask to `in progress` for the coding owner.
 - **Documentation Gate:** Validator/QA must fail validation when final documentation is missing or outdated; `Definition` is only the plan contract, not the delivered documentation.
 - **QA Output Contract:** QA handoffs should state the test strategy used, the results observed, the AC coverage achieved, any documentation impact, open risks, and the recommended next step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defend-tech/opencode-optima",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"