@defend-tech/opencode-optima 0.1.46 → 0.1.48

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,41 @@ 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;
+  return true;
+}
 function determineClickUpMergeAuthority({ isSubtask = false, clickupStatus = "", validationPassed = false, mergeFailed = false, finalApprovalRoles = CLICKUP_FINAL_APPROVER_ROLES, humansRegistry } = {}) {
   if (mergeFailed) {
     return {
@@ -9015,7 +9050,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 = [];
@@ -9882,9 +9918,10 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   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 };
 }
-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 +9929,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");
 }
@@ -10077,7 +10117,8 @@ async function withClickUpTaskRouteLock(taskId, operation) {
 async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, ensureTaskWorktree = ensureClickUpTaskWorktree, verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery, saveState = null, now = () => /* @__PURE__ */ new Date(), host = os.hostname(), commentLedgerPath = clickUpCommentLedgerPath(worktree) } = {}) {
   const eventType = clickUpEventType(payload);
   const eventKey = clickUpWebhookEventKey(payload);
-  const remembered = rememberClickUpWebhookEvent(state, eventKey);
+  const isStartupAssignmentReconciliation = payload?.startup_reconciliation === true && eventType === "taskAssigneeUpdated";
+  const remembered = isStartupAssignmentReconciliation ? { duplicate: false, state } : rememberClickUpWebhookEvent(state, eventKey);
   if (remembered.duplicate) return { ok: true, action: "ignored", reason: "duplicate", eventKey };
   let stateToPersist = remembered.state;
   let commentLedgerKey = "";
@@ -10144,7 +10185,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) {
@@ -10191,7 +10233,7 @@ 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, 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 };
   let authorizedUserId = "";
   if (clickupClient?.getAuthorizedUser) {
@@ -10209,7 +10251,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);
@@ -10238,18 +10280,41 @@ 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)
+      };
+      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;
@@ -10272,6 +10337,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
           sessionExists,
           createSession,
           sendSessionEvent,
+          verifySessionEventDelivery,
           saveState: persistState,
           now
         });
@@ -10283,8 +10349,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 {
@@ -11402,6 +11472,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`);

package/dist/sanitize_cli.js

@@ -8137,6 +8137,41 @@ 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;
+  return true;
+}
 function determineClickUpMergeAuthority({ isSubtask = false, clickupStatus = "", validationPassed = false, mergeFailed = false, finalApprovalRoles = CLICKUP_FINAL_APPROVER_ROLES, humansRegistry } = {}) {
   if (mergeFailed) {
     return {
@@ -9022,7 +9057,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 = [];
@@ -9889,9 +9925,10 @@ async function recoverClickUpPmSession({ openCodeClient, sendSessionEvent, click
   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 };
 }
-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 +9936,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");
 }
@@ -10084,7 +10124,8 @@ async function withClickUpTaskRouteLock(taskId, operation) {
 async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, ensureTaskWorktree = ensureClickUpTaskWorktree, verifySessionEventDelivery = verifyOpenCodeSessionEventDelivery, saveState = null, now = () => /* @__PURE__ */ new Date(), host = os.hostname(), commentLedgerPath = clickUpCommentLedgerPath(worktree) } = {}) {
   const eventType = clickUpEventType(payload);
   const eventKey = clickUpWebhookEventKey(payload);
-  const remembered = rememberClickUpWebhookEvent(state, eventKey);
+  const isStartupAssignmentReconciliation = payload?.startup_reconciliation === true && eventType === "taskAssigneeUpdated";
+  const remembered = isStartupAssignmentReconciliation ? { duplicate: false, state } : rememberClickUpWebhookEvent(state, eventKey);
   if (remembered.duplicate) return { ok: true, action: "ignored", reason: "duplicate", eventKey };
   let stateToPersist = remembered.state;
   let commentLedgerKey = "";
@@ -10151,7 +10192,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) {
@@ -10198,7 +10240,7 @@ 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, 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 };
   let authorizedUserId = "";
   if (clickupClient?.getAuthorizedUser) {
@@ -10216,7 +10258,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);
@@ -10245,18 +10287,41 @@ 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)
+      };
+      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;
@@ -10279,6 +10344,7 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
           sessionExists,
           createSession,
           sendSessionEvent,
+          verifySessionEventDelivery,
           saveState: persistState,
           now
         });
@@ -10290,8 +10356,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 {
@@ -11409,6 +11479,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`);

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.46",
+  "version": "0.1.48",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"