@defend-tech/opencode-optima 0.1.79 → 0.1.81

package/Agents_Common.md

@@ -13,6 +13,7 @@
 - Use the ClickUp skill and ClickUp MCP/tools for all ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboard operations; if unavailable or forbidden, state the sync blocker and leave a manual-sync payload in task/evidence.
 - Before writing ClickUp updates from local artifacts, use Optima Markdown-driven sync tools (`optima_clickup_start_task`, `optima_clickup_sync_summary`, `optima_clickup_transition`, `optima_clickup_create_subtasks`, `optima_clickup_apply_payload`) to derive payloads from `.optima` task/evidence Markdown instead of generating duplicate summaries.
 - Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs are the right source and must be posted to the linked ClickUp task/subtask comments or fields; subtasks come from strict plan/Definition `## Subtasks` sections via `optima_clickup_create_subtasks`.
+- Final task handoffs must go through `optima_finish` when available. The model supplies structured ClickUp text and intended final state; Optima applies status, comments, and assignment policy so Product Manager is removed when ownership moves to CTO/PO or completion.
 - ClickUp comments are human-facing model updates only. Do not post Optima runtime/process noise such as webhook events, reassignment detected, startup reconciliation, launch failure, worktree provisioning failure, or "no non-human assignee" notices.
 - ClickUp comments must be professional Markdown with real line breaks, not one long paragraph. Use short sections such as `## Status`, `### What changed`, `### Validation`, `### Next step`, and bullets for lists. Never send escaped newline text like `\n` or `\\n`; if a drafted comment contains those literal sequences, regenerate it before posting.
 - WPM rewrites the ClickUp task description on initial pickup and again at plan completion with the complete current/final description of what must be done, distinct from comments.
@@ -20,8 +21,8 @@
 - `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` 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 with `Story Points`, `Definition`, and test strategy, `in progress` execute, `validation` Tech Lead + Validator/QA gates, and parent post-approval merge automation. Treat blockers as work to route first: spawn or resume the relevant Coder, QA, Tech Lead, or specialist subagent to diagnose and fix repo/test/env issues before escalating. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, true external `in progress` blockers from missing credentials/permissions/tools/access after attempted local resolution, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, partial-phase stops, local dependency/test failures that a subagent can fix, or "no non-human assignee" fallback. For a true external `in progress` blocker, escalation means a castellano ClickUp help request explaining exactly what is needed, task assignment to CTO/PO, and Product Manager assignee removal, not only a comment or repeated PM nudge. Validator/QA may merge validated subtasks into the parent branch without CTO/PO approval; parent human `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code. `completed`/`Closed` ignore unless reopened.
+- Human role registry: resolve `CTO` and `PO` from available human role context and configured ClickUp IDs. Missing repo-local human registry files are an internal routing detail, not a task status; do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics. Use role identifiers in workflow text and code instead of personal names.
+- ClickUp status actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy, `in progress` execute, `validation` Tech Lead + Validator/QA gates, and parent post-approval merge automation. Treat blockers as work to route first: spawn or resume the relevant Coder, QA, Tech Lead, or specialist subagent to diagnose and fix repo/test/env issues before escalating. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, true external `in progress` blockers from missing credentials/permissions/tools/access after attempted local resolution, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, partial-phase stops, local dependency/test failures that a subagent can fix, or "no non-human assignee" fallback. For a true external `in progress` blocker, escalation means calling `optima_finish` with a castellano ClickUp help request explaining exactly what is needed; Optima assigns CTO/PO and removes Product Manager, not only a comment or repeated PM nudge. Validator/QA may merge validated subtasks into the parent branch without CTO/PO approval; parent human `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code. `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>`.
 - Clarifications, blockers, dependencies, and reviews go through PMA.

package/Agents_Common.prompt.md

@@ -15,6 +15,7 @@
 - Use the ClickUp skill and ClickUp MCP/tools for all ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboard operations; if unavailable or forbidden, state the sync blocker and leave a manual-sync payload in task/evidence.
 - Before writing ClickUp updates from local artifacts, use Optima Markdown-driven sync tools (`optima_clickup_start_task`, `optima_clickup_sync_summary`, `optima_clickup_transition`, `optima_clickup_create_subtasks`, `optima_clickup_apply_payload`) to derive payloads from `.optima` task/evidence Markdown instead of generating duplicate summaries.
 - Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs are the right source and must be posted to the linked ClickUp task/subtask comments or fields; subtasks come from strict plan/Definition `## Subtasks` sections via `optima_clickup_create_subtasks`.
+- Final task handoffs must go through `optima_finish` when available. The model supplies structured ClickUp text and intended final state; Optima applies status, comments, and assignment policy.
 - ClickUp comments are human-facing model updates only. Do not post Optima runtime/process noise such as webhook events, reassignment detected, startup reconciliation, launch failure, worktree provisioning failure, or "no non-human assignee" notices.
 - ClickUp comments must be professional Markdown with real line breaks, not one long paragraph. Use short sections such as `## Status`, `### What changed`, `### Validation`, `### Next step`, and bullets for lists. Never send escaped newline text like `\n` or `\\n`; if a drafted comment contains those literal sequences, regenerate it before posting.
 - WPM rewrites the ClickUp task description on initial pickup and again at plan completion with the complete current/final description of what must be done, distinct from comments.
@@ -22,8 +23,8 @@
 - `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` 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 with `Story Points`, `Definition`, and test strategy, `in progress` execute, `validation` Tech Lead + Validator/QA gates, and parent post-approval merge automation. Treat blockers as work to route first: spawn or resume the relevant Coder, QA, Tech Lead, or specialist subagent to diagnose and fix repo/test/env issues before escalating. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, true external `in progress` blockers from missing credentials/permissions/tools/access after attempted local resolution, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, partial-phase stops, local dependency/test failures that a subagent can fix, or "no non-human assignee" fallback. For a true external `in progress` blocker, escalation means a castellano ClickUp help request explaining exactly what is needed, task assignment to CTO/PO, and Product Manager assignee removal, not only a comment or repeated PM nudge. Validator/QA may merge validated subtasks into the parent branch without CTO/PO approval; parent human `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code. `completed`/`Closed` ignore unless reopened.
+- Human role registry: resolve `CTO` and `PO` from available human role context/configured ClickUp IDs. Missing repo-local human registry files are internal routing detail; do not mention internal role-resolution details in ClickUp comments unless asked for routing diagnostics.
+- ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy, `in progress` execute, `validation` Tech Lead + Validator/QA gates, and parent post-approval merge automation. Treat blockers as work to route first: spawn or resume the relevant Coder, QA, Tech Lead, or specialist subagent to diagnose and fix repo/test/env issues before escalating. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, true external `in progress` blockers from missing credentials/permissions/tools/access after attempted local resolution, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, partial-phase stops, local dependency/test failures that a subagent can fix, or "no non-human assignee" fallback. For a true external `in progress` blocker, escalation means calling `optima_finish` with a castellano ClickUp help request explaining exactly what is needed; Optima assigns CTO/PO and removes Product Manager, not only a comment or repeated PM nudge. Validator/QA may merge validated subtasks into the parent branch without CTO/PO approval; parent human `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code. `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.
 - Read relevant docs/tasks fully when they govern the current work. Prefer targeted CodeMap navigation before broad source search.

package/assets/agents/workflow_product_manager.md

@@ -7,6 +7,7 @@ tools:
   optima_start_discussion: true
   optima_stop_discussion: true
   optima_prompt_workflow: true
+  optima_finish: true
   optima_github_auth_mode: true
   optima_github_create_pr: true
   optima_github_comment_pr: true
@@ -38,6 +39,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - Store `agent_metadata` JSON with session IDs per agent/type/task/subtask and update it whenever an agent session starts or responsibility changes.
 - You are already the ClickUp task workflow; never launch nested/generic `optima_run_workflow` sessions.
 - Use `optima_prompt_workflow` only to prompt/resume an existing task-owned `workflow_runner` session whose session id is already registered in `agent_metadata` for the current task/subtask. Do not use it to launch generic workflows or unregistered sessions.
+- Finish/handoff rule: when work is ready for human validation, completed, blocked by external access, or otherwise leaving Product Manager ownership, call `optima_finish` instead of manually changing ClickUp status, comments, or assignees. Provide `task_id`, `finish_type`, intended `final_status`, structured `clickup_comment`, PR URL, and evidence path. Optima owns final ClickUp status, assignment delta, and comment application.
 
 ## Webhook And Intake
 
@@ -49,12 +51,12 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 
 ## Status Actions
 
-- Human registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in the task worktree, use the Optima-provided Human Role Fallback Registry and configured ClickUp IDs instead of blocking solely on the missing repo-local file.
+- Human registry: resolve `CTO` and `PO` from available human role context and configured ClickUp IDs. Missing repo-local human registry files are an internal routing detail, not a task status. Never mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics.
 - Human approval allowlist: never assign `CTO`/`PO` except for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. Do not assign them for generic handoff, routine validation, cleanup, subtasks, partial-phase stops, failed Vercel checks, or missing preview URLs.
-- External blocker handoff protocol: if local/subagent attempts are exhausted and the blocker is missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access, do all four actions in this order: (1) write one concise ClickUp comment in castellano using the sections `## Bloqueo externo`, `### Qué he intentado`, `### Qué necesito de CTO/PO`, and `### Cómo se desbloquea`; (2) assign the ClickUp task to `CTO`/`PO` using resolved or fallback IDs; (3) remove the Product Manager assignee; (4) stop re-queueing Product Manager until a human replies, reassigns the task, or the missing access becomes available. Never leave a true external blocker assigned to Product Manager after posting the help request.
+- External blocker handoff protocol: if local/subagent attempts are exhausted and the blocker is missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access, call `optima_finish` with `finish_type=external_blocker` and a concise castellano comment using the sections `## Bloqueo externo`, `### Qué he intentado`, `### Qué necesito de CTO/PO`, and `### Cómo se desbloquea`. Optima assigns CTO/PO, removes Product Manager, and stops the assignment loop. Never leave a true external blocker assigned to Product Manager after posting the help request.
 - `backlog`: ignore until prioritized.
 - `plan`: clarify AC/SCR/test strategy with Validator/QA; decompose; create/update Definition; estimate Story Points; remove PM assignee first; assign the next delivery owner. Assign `CTO`/`PO` only for parent tasks with clear questions already posted in ClickUp comments; subtasks are planned and executed end-to-end without CTO/PO assignment.
-- `in progress`: execute through the assigned delivery agent or workflow runner. Treat blockers as work to solve first: spawn or resume Coder for code/build/dependency failures, QA for validation/test/evidence failures, Tech Lead for architecture/review/merge failures, and the relevant specialist for domain blockers. Escalate to `CTO`/`PO` only when genuinely blocked by missing credentials, permissions, external tools, authenticated browser/Agent Jake access, or live third-party access after local/subagent resolution attempts; the escalation is a ClickUp assignment to CTO/PO plus Product Manager removal, not just a comment. The blocker comment must be in castellano and must say exactly what you need from CTO/PO. Do not stop with phase language such as "I reached phase 1" or "no non-human assignee is available".
+- `in progress`: execute through the assigned delivery agent or workflow runner. Treat blockers as work to solve first: spawn or resume Coder for code/build/dependency failures, QA for validation/test/evidence failures, Tech Lead for architecture/review/merge failures, and the relevant specialist for domain blockers. Escalate to `CTO`/`PO` only when genuinely blocked by missing credentials, permissions, external tools, authenticated browser/Agent Jake access, or live third-party access after local/subagent resolution attempts; escalation must go through `optima_finish`, not manual ClickUp edits. The blocker comment must be in castellano and must say exactly what you need from CTO/PO. Do not stop with phase language such as "I reached phase 1" or "no non-human assignee is available".
 - `validation`: before moving any task/subtask into Validation, create or update the required GitHub PR through `optima_github_create_pr`, store its URL/number in ClickUp `agent_metadata`, and leave a concise model-owned ClickUp status comment with the PR link, source branch, target branch, and current validation owner. Subtasks PR from their subtask branch into the parent task branch. Parent tasks PR from the task branch into `dev`. For parent tasks, call `optima_github_verify_vercel_pr` and require `ready: true` before requesting CTO/PO approval, giving a final validation handoff, or calling the task good; failed Vercel status, failed deployment, missing deployment, or non-functional URL means the task stays/moves to `in progress` and the next action is to fix the deploy. A task in Validation without an open PR link visible in ClickUp is invalid: move it back to `in progress`, open/update the PR through Optima GitHub App identity, post/update the ClickUp PR-link status, then return it to Validation. Route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks.
 - GitHub review wakeups: keep listening for PR review/comment webhooks. Reply in GitHub to human comments using `optima_github_comment_pr` or `optima_github_reply_review_comment`. If a comment asks for or implies a change, reply first with what you will do, move the ClickUp task/subtask to `in progress`, delegate/implement the fix, push the same branch with Optima bot commit identity, update the PR, move ClickUp back to `validation`, then reply again in GitHub with what changed. Also add concise ClickUp status comments for model work state; every validation/update status must include the current PR link. Never post Optima runtime/process noise.
 - `merge`: parent-only post-approval automation after the configured final approver/CTO approves the GitHub PR. The GitHub accepted/approved review is the merge trigger. Merge the parent PR into `dev`, verify the Vercel preproduction deployment updates automatically, run a small smoke/regression against preproduction, and only then clean workspaces/worktrees/branches and move ClickUp to `completed`. If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent task, move the parent back to `in progress`, and keep the evidence/PR links in ClickUp.

package/dist/index.js

@@ -10983,11 +10983,11 @@ ${additionFragment}`;
       if (humanRoleLines) {
         agentConfig.prompt = `${agentConfig.prompt}
 
-## Optima Human Role Fallback Registry
+## Optima Internal Human Role Context
 
 ${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.`;
+Use this internal context silently for CTO/PO assignment decisions. Do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics.`;
       }
     }
     ourAgents[id] = agentConfig;
@@ -11288,15 +11288,45 @@ function createClickUpApiClient(config, fetchImpl = globalThis.fetch) {
     async getTask(taskId) {
       return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`);
     },
+    async updateTask({ taskId, updates = {} }) {
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify(updates)
+      });
+    },
+    async updateTaskStatus({ taskId, status }) {
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify({ status })
+      });
+    },
     async updateTaskMetadata({ taskId, fieldId, value }) {
       return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}/field/${encodeURIComponent(fieldId)}`, {
         method: "POST",
         body: JSON.stringify({ value })
       });
     },
+    async updateTaskAssignees({ taskId, add = [], remove = [] }) {
+      const body = { assignees: {} };
+      const addIds = [...new Set((add || []).map((id) => String(id || "").trim()).filter(Boolean))];
+      const removeIds = [...new Set((remove || []).map((id) => String(id || "").trim()).filter(Boolean))];
+      if (addIds.length > 0) body.assignees.add = addIds;
+      if (removeIds.length > 0) body.assignees.rem = removeIds;
+      if (!body.assignees.add && !body.assignees.rem) return { ok: true, skipped: true, reason: "empty_assignee_update" };
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify(body)
+      });
+    },
     async postTaskComment() {
       throw new Error("Optima runtime does not post ClickUp task comments; use local logs for process failures.");
     },
+    async postModelTaskComment({ taskId, comment }) {
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}/comment`, {
+        method: "POST",
+        body: JSON.stringify({ comment_text: String(comment || "") })
+      });
+    },
     async addTaskTag() {
       throw new Error("Optima runtime does not add ClickUp task tags; use local logs for process failures.");
     },
@@ -11338,9 +11368,21 @@ function createTestClickUpApiClient(config) {
       metadata.set(String(taskId || ""), value);
       return { ok: true };
     },
+    async updateTask() {
+      return { ok: true };
+    },
+    async updateTaskStatus() {
+      return { ok: true };
+    },
+    async updateTaskAssignees() {
+      return { ok: true };
+    },
     async postTaskComment() {
       return { ok: true };
     },
+    async postModelTaskComment() {
+      return { ok: true };
+    },
     async addTaskTag() {
       return { ok: true };
     },
@@ -11701,6 +11743,53 @@ function clickUpWebhookLifecycleLog(worktree, entry) {
 var activeClickUpWebhookListeners = /* @__PURE__ */ new Map();
 var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
+var CLICKUP_HUMAN_HANDOFF_TEXT_PATTERNS = [
+  /\bhuman validation requested\b/i,
+  /\bhuman validation\/approval\b/i,
+  /\bplease review pr\b/i,
+  /\bapprove or request changes\b/i,
+  /\bCTO\/PO\b/i,
+  /\bBloqueo externo\b/i,
+  /\bQué necesito de CTO\/PO\b/i,
+  /\bCómo se desbloquea\b/i
+];
+function clickUpCommentCollectionText(response = {}) {
+  return clickUpCommentListItems(response).map((comment) => clickUpCommentText(comment)).filter(Boolean).join("\n\n");
+}
+function hasClickUpHumanHandoffText(text = "") {
+  const value = String(text || "");
+  return value.length > 0 && CLICKUP_HUMAN_HANDOFF_TEXT_PATTERNS.some((pattern) => pattern.test(value));
+}
+function configuredHumanRoleAssigneeIds(config = {}) {
+  const roleIds = config.routing?.humanRoleClickUpIds || {};
+  return [...new Set(["CTO", "PO"].map((role) => String(roleIds[role] || "").trim()).filter(Boolean))];
+}
+async function selfHealClickUpHumanHandoffAssignment({ clickupClient, config, worktree = process.cwd(), taskId, task, commentsResponse = null } = {}) {
+  const productManagerAssigneeId = String(config?.routing?.productManagerAssigneeId || "").trim();
+  if (!taskId || !productManagerAssigneeId || !isClickUpTaskAssignedToProductManager(task, productManagerAssigneeId)) return { changed: false, reason: "not_pm_assigned" };
+  if (typeof clickupClient?.updateTaskAssignees !== "function") return { changed: false, reason: "assignee_update_unavailable" };
+  const humanAssigneeIds = configuredHumanRoleAssigneeIds(config);
+  if (humanAssigneeIds.length === 0) return { changed: false, reason: "missing_human_role_ids" };
+  let candidateText = "";
+  if (commentsResponse) candidateText = clickUpCommentCollectionText(commentsResponse);
+  if (!candidateText && typeof clickupClient?.getTaskComments === "function") {
+    try {
+      const response = await clickupClient.getTaskComments({ taskId, limit: CLICKUP_WEBHOOK_STARTUP_COMMENT_LIMIT });
+      candidateText = clickUpCommentCollectionText(response);
+    } catch (error) {
+      appendClickUpWebhookLocalLog(worktree, { type: "human_handoff_comment_scan_failed", taskId, message: error.message });
+    }
+  }
+  if (!hasClickUpHumanHandoffText(candidateText)) return { changed: false, reason: "no_human_handoff_signal" };
+  try {
+    await clickupClient.updateTaskAssignees({ taskId, add: humanAssigneeIds, remove: [productManagerAssigneeId] });
+    appendClickUpWebhookLocalLog(worktree, { type: "human_handoff_assignment_self_healed", taskId, add: humanAssigneeIds, remove: [productManagerAssigneeId] });
+    return { changed: true, reason: "human_handoff_assignment_self_healed", add: humanAssigneeIds, remove: [productManagerAssigneeId] };
+  } catch (error) {
+    appendClickUpWebhookLocalLog(worktree, { type: "human_handoff_assignment_self_heal_failed", taskId, add: humanAssigneeIds, remove: [productManagerAssigneeId], message: error.message });
+    return { changed: false, reason: "assignee_update_failed", message: error.message };
+  }
+}
 async function ensureClickUpTaskWorktreeForWebhook({ opencodeBaseUrl = "", opencodeBaseUrlConfigured = false, openchamberBaseUrl = "", openchamberBaseUrlConfigured = false, clickupClient = null, webhookWorktree = process.cwd(), fetchImpl = globalThis.fetch, ...options } = {}) {
   void opencodeBaseUrlConfigured;
   if (!openchamberBaseUrlConfigured || !openchamberBaseUrl) return ensureClickUpTaskWorktree(options);
@@ -12090,13 +12179,13 @@ 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 ? "Internal human role context for silent CTO/PO assignment decisions:" : 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 local/subagent attempts are exhausted and the blocker is missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access, post the concrete help request in castellano using sections ## Bloqueo externo, ### Qu\xE9 he intentado, ### Qu\xE9 necesito de CTO/PO, and ### C\xF3mo se desbloquea; then assign CTO/PO using fallback registry IDs, remove the Product Manager assignee, and stop re-queueing Product Manager until a human replies or reassigns the task. Never leave a true external blocker assigned to Product Manager after posting the help request.",
-    "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.",
+    "If local/subagent attempts are exhausted and the blocker is missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access, post the concrete help request in castellano using sections ## Bloqueo externo, ### Qu\xE9 he intentado, ### Qu\xE9 necesito de CTO/PO, and ### C\xF3mo se desbloquea; then assign CTO/PO using the internal role context/configured IDs, remove the Product Manager assignee, and stop re-queueing Product Manager until a human replies or reassigns the task. Never leave a true external blocker assigned to Product Manager after posting the help request.",
+    "Use internal human role context silently. Do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics.",
     deliveryEvidencePath ? `Final merge-trackable evidence must be written under ${deliveryEvidencePath}; use .optima only as local mirror/staging.` : null
   ].filter((part) => part !== null).join("\n");
 }
@@ -12525,6 +12614,12 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
       routed.ignored += 1;
       continue;
     }
+    const humanHandoffSelfHeal = await selfHealClickUpHumanHandoffAssignment({ clickupClient, config, worktree, taskId, task });
+    if (humanHandoffSelfHeal.changed) {
+      routed.ignored += 1;
+      routed.tasks.push({ taskId, action: "self_healed_human_handoff_assignment", ok: true, sessionId: null, branch: null, worktree: null, verification: humanHandoffSelfHeal.reason, delivered: false });
+      continue;
+    }
     if (watchdogMode) {
       const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
       const metadata = normalizeAgentMetadataJson(existingMetadata);
@@ -14181,6 +14276,55 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
     }
     return { ok: true, auth };
   };
+  const finishClickUpTask = async ({ taskId, finishType = "", finalStatus = "", comment = "", prUrl = "", evidencePath = "" } = {}) => {
+    if (!clickUpWebhookValidation.complete) return { ok: false, error: "clickup_not_configured" };
+    if (!runtimeClickUpClient?.getTask) return { ok: false, error: "clickup_client_unavailable" };
+    const normalizedTaskId = String(taskId || "").trim();
+    if (!normalizedTaskId) return { ok: false, error: "task_id_required" };
+    const normalizedFinishType = String(finishType || "").trim().toLowerCase().replace(/[\s-]+/g, "_");
+    const inferredStatus = normalizedFinishType === "external_blocker" ? "in progress" : normalizedFinishType === "human_validation" ? "validation" : normalizedFinishType === "completed" ? "completed" : "";
+    const status = String(finalStatus || inferredStatus || "").trim();
+    const routing = clickUpWebhookValidation.config.routing || {};
+    const productManagerAssigneeId = String(routing.productManagerAssigneeId || "").trim();
+    const humanAssignees = ["CTO", "PO"].map((role) => String(routing.humanRoleClickUpIds?.[role] || "").trim()).filter(Boolean);
+    const addAssignees = ["external_blocker", "human_validation"].includes(normalizedFinishType) ? humanAssignees : [];
+    const removeAssignees = ["external_blocker", "human_validation", "completed"].includes(normalizedFinishType) && productManagerAssigneeId ? [productManagerAssigneeId] : [];
+    const task = await runtimeClickUpClient.getTask(normalizedTaskId);
+    const currentAssignees = clickUpAssigneeIds(task);
+    const assignmentDelta = {
+      add: [...new Set(addAssignees.filter((id) => !currentAssignees.includes(id)))],
+      remove: [...new Set(removeAssignees.filter((id) => currentAssignees.includes(id)))]
+    };
+    const applied = [];
+    if (status && runtimeClickUpClient.updateTaskStatus) {
+      await runtimeClickUpClient.updateTaskStatus({ taskId: normalizedTaskId, status });
+      applied.push("status");
+    }
+    if ((assignmentDelta.add.length > 0 || assignmentDelta.remove.length > 0) && runtimeClickUpClient.updateTaskAssignees) {
+      await runtimeClickUpClient.updateTaskAssignees({ taskId: normalizedTaskId, add: assignmentDelta.add, remove: assignmentDelta.remove });
+      applied.push("assignees");
+    }
+    const normalizedComment = String(comment || "").replace(/\\r\\n/g, "\n").replace(/\\n/g, "\n").trim();
+    const commentWithContext = [
+      normalizedComment,
+      prUrl ? `
+PR: ${prUrl}` : "",
+      evidencePath ? `
+Evidencia: ${evidencePath}` : ""
+    ].join("").trim();
+    if (commentWithContext && runtimeClickUpClient.postModelTaskComment) {
+      await runtimeClickUpClient.postModelTaskComment({ taskId: normalizedTaskId, comment: commentWithContext });
+      applied.push("comment");
+    }
+    return {
+      ok: true,
+      taskId: normalizedTaskId,
+      finishType: normalizedFinishType || "status_update",
+      status: status || null,
+      assignmentDelta,
+      applied
+    };
+  };
   const tools = {
     optima_init: tool({
       description: "Initialize the Optima workflow and CodeMap in the current repository",
@@ -14395,6 +14539,32 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         return JSON.stringify(payload, null, 2);
       }
     }),
+    optima_finish: tool({
+      description: "Finish or hand off a ClickUp task through Optima. The model provides structured ClickUp text and intended final state; Optima applies status, comment, and assignment policy.",
+      args: {
+        task_id: tool.schema.string().describe("ClickUp task ID to finish or hand off"),
+        finish_type: tool.schema.string().describe("One of: completed, human_validation, external_blocker, needs_work, status_update"),
+        final_status: tool.schema.string().describe("Optional ClickUp status to set. If empty, Optima infers from finish_type where possible."),
+        clickup_comment: tool.schema.string().describe("Human-facing structured ClickUp comment text with real line breaks. Use castellano for blocker/help comments."),
+        pr_url: tool.schema.string().describe("Optional GitHub PR URL to include in the final ClickUp comment"),
+        evidence_path: tool.schema.string().describe("Optional evidence path to include in the final ClickUp comment")
+      },
+      async execute(args) {
+        try {
+          const result = await finishClickUpTask({
+            taskId: args.task_id,
+            finishType: args.finish_type,
+            finalStatus: args.final_status,
+            comment: args.clickup_comment,
+            prUrl: args.pr_url,
+            evidencePath: args.evidence_path
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
     optima_clickup_create_subtasks: tool({
       description: "Generate dry-run ClickUp subtask creation payloads from a strict Markdown ## Subtasks section",
       args: {
@@ -14963,7 +15133,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, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createGitHubApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, gitHubPullRequestContextFromPayload, gitHubWebhookExpectedPath, handleClickUpWebhookRequest, handleGitHubWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, routeGitHubWebhookEvent, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, verifyGitHubSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, 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, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createGitHubApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, gitHubPullRequestContextFromPayload, gitHubWebhookExpectedPath, handleClickUpWebhookRequest, handleGitHubWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, routeGitHubWebhookEvent, scheduleClickUpAssignmentWatchdog, selfHealClickUpHumanHandoffAssignment, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, verifyGitHubSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 export {
   OptimaPlugin as default
 };

package/dist/sanitize_cli.js

@@ -10990,11 +10990,11 @@ ${additionFragment}`;
       if (humanRoleLines) {
         agentConfig.prompt = `${agentConfig.prompt}
 
-## Optima Human Role Fallback Registry
+## Optima Internal Human Role Context
 
 ${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.`;
+Use this internal context silently for CTO/PO assignment decisions. Do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics.`;
       }
     }
     ourAgents[id] = agentConfig;
@@ -11295,15 +11295,45 @@ function createClickUpApiClient(config, fetchImpl = globalThis.fetch) {
     async getTask(taskId) {
       return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`);
     },
+    async updateTask({ taskId, updates = {} }) {
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify(updates)
+      });
+    },
+    async updateTaskStatus({ taskId, status }) {
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify({ status })
+      });
+    },
     async updateTaskMetadata({ taskId, fieldId, value }) {
       return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}/field/${encodeURIComponent(fieldId)}`, {
         method: "POST",
         body: JSON.stringify({ value })
       });
     },
+    async updateTaskAssignees({ taskId, add = [], remove = [] }) {
+      const body = { assignees: {} };
+      const addIds = [...new Set((add || []).map((id) => String(id || "").trim()).filter(Boolean))];
+      const removeIds = [...new Set((remove || []).map((id) => String(id || "").trim()).filter(Boolean))];
+      if (addIds.length > 0) body.assignees.add = addIds;
+      if (removeIds.length > 0) body.assignees.rem = removeIds;
+      if (!body.assignees.add && !body.assignees.rem) return { ok: true, skipped: true, reason: "empty_assignee_update" };
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}`, {
+        method: "PUT",
+        body: JSON.stringify(body)
+      });
+    },
     async postTaskComment() {
       throw new Error("Optima runtime does not post ClickUp task comments; use local logs for process failures.");
     },
+    async postModelTaskComment({ taskId, comment }) {
+      return request(`https://api.clickup.com/api/v2/task/${encodeURIComponent(taskId)}/comment`, {
+        method: "POST",
+        body: JSON.stringify({ comment_text: String(comment || "") })
+      });
+    },
     async addTaskTag() {
       throw new Error("Optima runtime does not add ClickUp task tags; use local logs for process failures.");
     },
@@ -11345,9 +11375,21 @@ function createTestClickUpApiClient(config) {
       metadata.set(String(taskId || ""), value);
       return { ok: true };
     },
+    async updateTask() {
+      return { ok: true };
+    },
+    async updateTaskStatus() {
+      return { ok: true };
+    },
+    async updateTaskAssignees() {
+      return { ok: true };
+    },
     async postTaskComment() {
       return { ok: true };
     },
+    async postModelTaskComment() {
+      return { ok: true };
+    },
     async addTaskTag() {
       return { ok: true };
     },
@@ -11708,6 +11750,53 @@ function clickUpWebhookLifecycleLog(worktree, entry) {
 var activeClickUpWebhookListeners = /* @__PURE__ */ new Map();
 var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
+var CLICKUP_HUMAN_HANDOFF_TEXT_PATTERNS = [
+  /\bhuman validation requested\b/i,
+  /\bhuman validation\/approval\b/i,
+  /\bplease review pr\b/i,
+  /\bapprove or request changes\b/i,
+  /\bCTO\/PO\b/i,
+  /\bBloqueo externo\b/i,
+  /\bQué necesito de CTO\/PO\b/i,
+  /\bCómo se desbloquea\b/i
+];
+function clickUpCommentCollectionText(response = {}) {
+  return clickUpCommentListItems(response).map((comment) => clickUpCommentText(comment)).filter(Boolean).join("\n\n");
+}
+function hasClickUpHumanHandoffText(text = "") {
+  const value = String(text || "");
+  return value.length > 0 && CLICKUP_HUMAN_HANDOFF_TEXT_PATTERNS.some((pattern) => pattern.test(value));
+}
+function configuredHumanRoleAssigneeIds(config = {}) {
+  const roleIds = config.routing?.humanRoleClickUpIds || {};
+  return [...new Set(["CTO", "PO"].map((role) => String(roleIds[role] || "").trim()).filter(Boolean))];
+}
+async function selfHealClickUpHumanHandoffAssignment({ clickupClient, config, worktree = process.cwd(), taskId, task, commentsResponse = null } = {}) {
+  const productManagerAssigneeId = String(config?.routing?.productManagerAssigneeId || "").trim();
+  if (!taskId || !productManagerAssigneeId || !isClickUpTaskAssignedToProductManager(task, productManagerAssigneeId)) return { changed: false, reason: "not_pm_assigned" };
+  if (typeof clickupClient?.updateTaskAssignees !== "function") return { changed: false, reason: "assignee_update_unavailable" };
+  const humanAssigneeIds = configuredHumanRoleAssigneeIds(config);
+  if (humanAssigneeIds.length === 0) return { changed: false, reason: "missing_human_role_ids" };
+  let candidateText = "";
+  if (commentsResponse) candidateText = clickUpCommentCollectionText(commentsResponse);
+  if (!candidateText && typeof clickupClient?.getTaskComments === "function") {
+    try {
+      const response = await clickupClient.getTaskComments({ taskId, limit: CLICKUP_WEBHOOK_STARTUP_COMMENT_LIMIT });
+      candidateText = clickUpCommentCollectionText(response);
+    } catch (error) {
+      appendClickUpWebhookLocalLog(worktree, { type: "human_handoff_comment_scan_failed", taskId, message: error.message });
+    }
+  }
+  if (!hasClickUpHumanHandoffText(candidateText)) return { changed: false, reason: "no_human_handoff_signal" };
+  try {
+    await clickupClient.updateTaskAssignees({ taskId, add: humanAssigneeIds, remove: [productManagerAssigneeId] });
+    appendClickUpWebhookLocalLog(worktree, { type: "human_handoff_assignment_self_healed", taskId, add: humanAssigneeIds, remove: [productManagerAssigneeId] });
+    return { changed: true, reason: "human_handoff_assignment_self_healed", add: humanAssigneeIds, remove: [productManagerAssigneeId] };
+  } catch (error) {
+    appendClickUpWebhookLocalLog(worktree, { type: "human_handoff_assignment_self_heal_failed", taskId, add: humanAssigneeIds, remove: [productManagerAssigneeId], message: error.message });
+    return { changed: false, reason: "assignee_update_failed", message: error.message };
+  }
+}
 async function ensureClickUpTaskWorktreeForWebhook({ opencodeBaseUrl = "", opencodeBaseUrlConfigured = false, openchamberBaseUrl = "", openchamberBaseUrlConfigured = false, clickupClient = null, webhookWorktree = process.cwd(), fetchImpl = globalThis.fetch, ...options } = {}) {
   void opencodeBaseUrlConfigured;
   if (!openchamberBaseUrlConfigured || !openchamberBaseUrl) return ensureClickUpTaskWorktree(options);
@@ -12097,13 +12186,13 @@ 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 ? "Internal human role context for silent CTO/PO assignment decisions:" : 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 local/subagent attempts are exhausted and the blocker is missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access, post the concrete help request in castellano using sections ## Bloqueo externo, ### Qu\xE9 he intentado, ### Qu\xE9 necesito de CTO/PO, and ### C\xF3mo se desbloquea; then assign CTO/PO using fallback registry IDs, remove the Product Manager assignee, and stop re-queueing Product Manager until a human replies or reassigns the task. Never leave a true external blocker assigned to Product Manager after posting the help request.",
-    "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.",
+    "If local/subagent attempts are exhausted and the blocker is missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access, post the concrete help request in castellano using sections ## Bloqueo externo, ### Qu\xE9 he intentado, ### Qu\xE9 necesito de CTO/PO, and ### C\xF3mo se desbloquea; then assign CTO/PO using the internal role context/configured IDs, remove the Product Manager assignee, and stop re-queueing Product Manager until a human replies or reassigns the task. Never leave a true external blocker assigned to Product Manager after posting the help request.",
+    "Use internal human role context silently. Do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics.",
     deliveryEvidencePath ? `Final merge-trackable evidence must be written under ${deliveryEvidencePath}; use .optima only as local mirror/staging.` : null
   ].filter((part) => part !== null).join("\n");
 }
@@ -12532,6 +12621,12 @@ async function reconcileClickUpStartup({ config, state = {}, worktree = process.
       routed.ignored += 1;
       continue;
     }
+    const humanHandoffSelfHeal = await selfHealClickUpHumanHandoffAssignment({ clickupClient, config, worktree, taskId, task });
+    if (humanHandoffSelfHeal.changed) {
+      routed.ignored += 1;
+      routed.tasks.push({ taskId, action: "self_healed_human_handoff_assignment", ok: true, sessionId: null, branch: null, worktree: null, verification: humanHandoffSelfHeal.reason, delivered: false });
+      continue;
+    }
     if (watchdogMode) {
       const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
       const metadata = normalizeAgentMetadataJson(existingMetadata);
@@ -14188,6 +14283,55 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
     }
     return { ok: true, auth };
   };
+  const finishClickUpTask = async ({ taskId, finishType = "", finalStatus = "", comment = "", prUrl = "", evidencePath = "" } = {}) => {
+    if (!clickUpWebhookValidation.complete) return { ok: false, error: "clickup_not_configured" };
+    if (!runtimeClickUpClient?.getTask) return { ok: false, error: "clickup_client_unavailable" };
+    const normalizedTaskId = String(taskId || "").trim();
+    if (!normalizedTaskId) return { ok: false, error: "task_id_required" };
+    const normalizedFinishType = String(finishType || "").trim().toLowerCase().replace(/[\s-]+/g, "_");
+    const inferredStatus = normalizedFinishType === "external_blocker" ? "in progress" : normalizedFinishType === "human_validation" ? "validation" : normalizedFinishType === "completed" ? "completed" : "";
+    const status = String(finalStatus || inferredStatus || "").trim();
+    const routing = clickUpWebhookValidation.config.routing || {};
+    const productManagerAssigneeId = String(routing.productManagerAssigneeId || "").trim();
+    const humanAssignees = ["CTO", "PO"].map((role) => String(routing.humanRoleClickUpIds?.[role] || "").trim()).filter(Boolean);
+    const addAssignees = ["external_blocker", "human_validation"].includes(normalizedFinishType) ? humanAssignees : [];
+    const removeAssignees = ["external_blocker", "human_validation", "completed"].includes(normalizedFinishType) && productManagerAssigneeId ? [productManagerAssigneeId] : [];
+    const task = await runtimeClickUpClient.getTask(normalizedTaskId);
+    const currentAssignees = clickUpAssigneeIds(task);
+    const assignmentDelta = {
+      add: [...new Set(addAssignees.filter((id) => !currentAssignees.includes(id)))],
+      remove: [...new Set(removeAssignees.filter((id) => currentAssignees.includes(id)))]
+    };
+    const applied = [];
+    if (status && runtimeClickUpClient.updateTaskStatus) {
+      await runtimeClickUpClient.updateTaskStatus({ taskId: normalizedTaskId, status });
+      applied.push("status");
+    }
+    if ((assignmentDelta.add.length > 0 || assignmentDelta.remove.length > 0) && runtimeClickUpClient.updateTaskAssignees) {
+      await runtimeClickUpClient.updateTaskAssignees({ taskId: normalizedTaskId, add: assignmentDelta.add, remove: assignmentDelta.remove });
+      applied.push("assignees");
+    }
+    const normalizedComment = String(comment || "").replace(/\\r\\n/g, "\n").replace(/\\n/g, "\n").trim();
+    const commentWithContext = [
+      normalizedComment,
+      prUrl ? `
+PR: ${prUrl}` : "",
+      evidencePath ? `
+Evidencia: ${evidencePath}` : ""
+    ].join("").trim();
+    if (commentWithContext && runtimeClickUpClient.postModelTaskComment) {
+      await runtimeClickUpClient.postModelTaskComment({ taskId: normalizedTaskId, comment: commentWithContext });
+      applied.push("comment");
+    }
+    return {
+      ok: true,
+      taskId: normalizedTaskId,
+      finishType: normalizedFinishType || "status_update",
+      status: status || null,
+      assignmentDelta,
+      applied
+    };
+  };
   const tools = {
     optima_init: tool({
       description: "Initialize the Optima workflow and CodeMap in the current repository",
@@ -14402,6 +14546,32 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         return JSON.stringify(payload, null, 2);
       }
     }),
+    optima_finish: tool({
+      description: "Finish or hand off a ClickUp task through Optima. The model provides structured ClickUp text and intended final state; Optima applies status, comment, and assignment policy.",
+      args: {
+        task_id: tool.schema.string().describe("ClickUp task ID to finish or hand off"),
+        finish_type: tool.schema.string().describe("One of: completed, human_validation, external_blocker, needs_work, status_update"),
+        final_status: tool.schema.string().describe("Optional ClickUp status to set. If empty, Optima infers from finish_type where possible."),
+        clickup_comment: tool.schema.string().describe("Human-facing structured ClickUp comment text with real line breaks. Use castellano for blocker/help comments."),
+        pr_url: tool.schema.string().describe("Optional GitHub PR URL to include in the final ClickUp comment"),
+        evidence_path: tool.schema.string().describe("Optional evidence path to include in the final ClickUp comment")
+      },
+      async execute(args) {
+        try {
+          const result = await finishClickUpTask({
+            taskId: args.task_id,
+            finishType: args.finish_type,
+            finalStatus: args.final_status,
+            comment: args.clickup_comment,
+            prUrl: args.pr_url,
+            evidencePath: args.evidence_path
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
     optima_clickup_create_subtasks: tool({
       description: "Generate dry-run ClickUp subtask creation payloads from a strict Markdown ## Subtasks section",
       args: {
@@ -14970,7 +15140,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, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createGitHubApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, gitHubPullRequestContextFromPayload, gitHubWebhookExpectedPath, handleClickUpWebhookRequest, handleGitHubWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, routeGitHubWebhookEvent, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, verifyGitHubSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, 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, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createGitHubApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, gitHubPullRequestContextFromPayload, gitHubWebhookExpectedPath, handleClickUpWebhookRequest, handleGitHubWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, routeGitHubWebhookEvent, scheduleClickUpAssignmentWatchdog, selfHealClickUpHumanHandoffAssignment, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, verifyGitHubSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, 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` 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.
+- Human role registry: resolve `CTO` and `PO` from available human role context and configured ClickUp IDs. Missing repo-local human registry files are an internal routing detail, not a task status; do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics. Use role identifiers in workflow text and automation config.
 - Status actions are deterministic: `backlog` ignore, `plan` plan plus `Story Points`, test strategy, and `Definition`, `in progress` execute, `validation` split Tech Lead and Validator/QA gates, `merge` parent post-approval automation, and `completed`/`Closed` ignore unless reopened.
 - Human approval assignment is prohibited except for the strict allowlist: parent `plan` with clear questions already posted in ClickUp comments; `in progress` blocked by missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access after local/subagent attempts; or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` for the current PR with a functional Vercel preproduction/preview URL. For true external `in progress` blockers, post the exact human action needed in castellano, assign CTO/PO in ClickUp, and remove Product Manager so PM watchdogs stop looping. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask planning/validation, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - 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.

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` 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.
+- Human role registry: resolve `CTO` and `PO` from available human role context/configured ClickUp IDs. Missing repo-local human registry files are internal routing detail; do not mention internal role-resolution details in ClickUp comments unless asked for routing diagnostics.
 - ClickUp-first statuses: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. True external `in progress` blockers require a castellano ClickUp help request, CTO/PO assignment, and Product Manager removal; subtasks merge directly into the parent branch after Validator/QA passes without CTO/PO assignment; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev/preproduction receives the code; `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 branches use `<type>/<parent-id>`; subtask branches use non-nested `<type>/<parent-id>-subtask-<subtask-id>` and pending subtasks use `<type>/<parent-id>-pending-<title-slug>`; parent task pulls remote once at start; subtasks start from and PR to the parent local branch, bootstrapping the parent from `dev`/`origin/dev` first when missing; PoC branches stay `poc/<clickup-task-id>`; 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` 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.
+- Human role registry: resolve `CTO` and `PO` from available human role context and configured ClickUp IDs. Missing repo-local human registry files are an internal routing detail, not a task status; do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics. Use role identifiers in workflow text and automation config.
 - Human approval assignment is prohibited except for three cases: parent `plan` with clear ClickUp-commented questions, true `in progress` blockers caused by missing credentials/permissions/tools/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel preproduction/preview URL. For those true external `in progress` blockers, assign CTO/PO in ClickUp, remove Product Manager, and explain the exact needed human action in a concise castellano ClickUp comment. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask work, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - Subtask merge authority belongs to Validator/QA after successful subtask validation: subtask PRs target and merge into the parent branch/workspace without `CTO`/`PO` assignment or approval.
 - Parent merge authority is split: after Tech Lead and Validator/QA pass plus a ready Vercel PR deployment gate, WPM/Validator may assign `CTO`/`PO` only under the parent-validation allowlist; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges to `dev`, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev/preproduction environment contains the code.

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` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
+- Human role registry: resolve `CTO` and `PO` from available human role context/configured ClickUp IDs. Missing repo-local human registry files are internal routing detail; do not mention internal role-resolution details in ClickUp comments unless asked for routing diagnostics.
 - Human approval assignment is prohibited except for parent `plan` questions with clear ClickUp comments, true `in progress` blockers from missing credentials/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. True external `in progress` blocker escalation means a concrete castellano help request, ClickUp assignment to CTO/PO, and Product Manager removal; never use it for generic handoff, cleanup, subtasks, phase stops, failed Vercel checks, or missing preview URLs.
 - Validator/QA may merge validated subtask PRs into the parent branch/workspace without `CTO`/`PO` assignment or approval.
 - Parent merge authority uses the validation allowlist only after a ready Vercel PR deployment gate: after a human comments `Approved`, automation removes human assignees, assigns merge owner/self, merges to `dev`, cleans workspaces/worktrees/branches, pushes, and ensures dev/preproduction receives the code.

package/docs/core/task_model.md

@@ -11,7 +11,8 @@
 - 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` 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.
+- Human role registry: resolve `CTO` and `PO` from available human role context and configured ClickUp IDs. Missing repo-local human registry files are an internal routing detail, not a task status; do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics. Use role identifiers in workflow text and automation config.
+- Final task handoffs must use `optima_finish` when available: the model supplies structured ClickUp text and intended final state, while Optima applies status, comments, and assignment policy.
 - Status-to-action mapping: `backlog` -> `ignore`, `plan` -> `plan`, `in progress` -> `execute`, `validation` -> `validate`, `merge` -> `merge`, `completed`/`Closed` -> `ignore` unless reopened. `plan` does not imply generic human approval assignment; `merge` is parent-only post-approval automation, while subtasks merge after successful Validator/QA validation without waiting for a human approval status.
 - Branch-safe type slugs are lowercase ASCII: `tarea`, `bug`, `doc`, `poc`.
 
@@ -19,7 +20,7 @@
 
 - Agents must not assign ClickUp tasks to `CTO` or `PO` except for the explicit cases below; generic handoff, routine validation, duplicate-assignee cleanup, or incomplete phase handoff are prohibited.
 - **Parent planning questions:** only a parent task in `plan` may assign `CTO`/`PO`, and only after clear, concrete questions have been posted in ClickUp comments. Subtasks are planned and executed end-to-end without CTO/PO planning assignment.
-- **Real in-progress blocker:** a task in `in progress` may assign/escalate to `CTO`/`PO` only when blocked by missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access after local/subagent attempts are exhausted. Escalation means posting a concrete ClickUp help request in castellano explaining exactly what is needed, assigning CTO/PO, and removing the Product Manager assignee so watchdogs stop re-queueing PM until a human replies/reassigns. Agents must not stop at informal phase boundaries such as "I reached phase 1"; phases should have been subtasks, otherwise finish the accepted task.
+- **Real in-progress blocker:** a task in `in progress` may assign/escalate to `CTO`/`PO` only when blocked by missing credentials, permissions, authenticated browser/Agent Jake access, external tools, or live third-party access after local/subagent attempts are exhausted. Escalation means calling `optima_finish` with a concrete ClickUp help request in castellano explaining exactly what is needed; Optima assigns CTO/PO and removes the Product Manager assignee so watchdogs stop re-queueing PM until a human replies/reassigns. Agents must not stop at informal phase boundaries such as "I reached phase 1"; phases should have been subtasks, otherwise finish the accepted task.
 - **Parent validation approval:** only a parent task in `validation` may assign `CTO`/`PO` for final validation, and only after `optima_github_verify_vercel_pr` returns `ready: true` for the current parent PR with a functional Vercel preproduction/preview URL. After a human comments `Approved`, automation reassigns to itself or the merge owner, removes human assignees, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev/preproduction environment contains the code.
 
 ## Routing Rules

package/docs/core/task_model.prompt.md

@@ -6,8 +6,9 @@
 - 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` 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`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. For true external `in progress` blockers, post a concrete castellano ClickUp help request explaining exactly what is needed, assign CTO/PO, and remove Product Manager so PM watchdogs stop looping until a human replies/reassigns. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev/preproduction receives the code; `completed`/`Closed` ignore unless reopened.
+- Human role registry: resolve `CTO` and `PO` from available human role context/configured ClickUp IDs. Missing repo-local human registry files are internal routing detail; do not mention internal role-resolution details in ClickUp comments unless asked for routing diagnostics.
+- Final task handoffs must use `optima_finish` when available; Optima applies final status, comment, and assignments.
+- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. For true external `in progress` blockers, call `optima_finish` with a concrete castellano ClickUp help request explaining exactly what is needed; Optima assigns CTO/PO and removes Product Manager so PM watchdogs stop looping until a human replies/reassigns. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev/preproduction receives the code; `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.
 - WPM stores `agent_metadata`, re-estimates `Story Points` on material plan changes, and keeps `Definition` plan contract separate from final Documentation.

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` 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.
+- **Human Role Registry:** Resolve `CTO` and `PO` from available human role context and configured ClickUp IDs. Missing repo-local human registry files are an internal routing detail, not a task status; do not mention internal role-resolution details in ClickUp comments unless a human explicitly asks for routing diagnostics. Use role identifiers in workflow text and automation config.
 - **Human Approval Allowlist:** Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/permissions/tools/access/authenticated browser or Agent Jake/live third-party access after local/subagent attempts, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. For true external `in progress` blockers, post the concrete help request in castellano, assign CTO/PO in ClickUp, and remove Product Manager. Never assign them for generic handoff, routine validation, cleanup, subtasks, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - **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 the parent-validation allowlist; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code. 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.

package/package.json

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