@defend-tech/opencode-optima 0.1.61 → 0.1.62

package/Agents_Common.md

@@ -19,7 +19,7 @@
 - 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 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.
+- 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. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, or partial-phase stops. 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

@@ -21,7 +21,7 @@
 - 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 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.
+- 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. Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL; never for generic handoff, cleanup, subtasks, or partial-phase stops. 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

@@ -15,7 +15,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - `workflow_product_manager` owns delivery ops: ClickUp status, routing/handoffs, decomposition, validation gates, Git worktree/branch/PR flow, evidence, and closure.
 - `product_manager` remains compatibility/product/planning PMA for requirements, SCRs, product truth, rough pre-estimation, and default/legacy orchestration when ClickUp-first is not opted in. Do not remove, shadow, or break `product_manager`.
 - ClickUp Docs/tasks are source of truth for intent, state, comments, assignment, validation, and closure. Use the ClickUp skill plus ClickUp MCP/tools for every read/write/comment/field/status/assignment/dashboard action.
-- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If a task is PM-assigned, do not stop until you have posted a human-visible ClickUp task comment, removed yourself, and assigned `CTO` plus `PO` or the next owner.
+- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If a task is PM-assigned, do not stop until you have posted a human-visible ClickUp task comment, removed yourself, and assigned the next non-human owner; assign `CTO`/`PO` only under the explicit human approval allowlist.
 - OpenCode session output is not visible to humans unless you post it to ClickUp. Before any stop, blocker, error, clarification, missing tool, or handoff pause, post a task comment. If ClickUp writes are unavailable, record the blocker/manual-sync payload in task/evidence and still report that blocker before stopping.
 - Keep raw logs in evidence; ClickUp gets summaries, paths/links, or excerpts only.
 
@@ -40,11 +40,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 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` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign them for generic handoff, routine validation, cleanup, subtasks, or partial-phase stops.
 - `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 `CTO` + `PO` or next owner; target zero PM-assigned tasks.
-- `in progress`: execute through the 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.
-- `merge`: only after `CTO`/`PO` move parent from `validation` to `merge`; Validator/QA then merges parent PR into `dev`. Conflicts or merge failures return the affected item to `in progress`.
+- `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. Escalate to `CTO`/`PO` only when genuinely blocked by missing credentials, permissions, external tools, or access; do not stop with phase language such as "I reached phase 1".
+- `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 parent tasks may assign `CTO`/`PO` only when a functional preview URL is provided.
+- `merge`: parent-only post-approval automation after a human comments `Approved`; remove human assignees, assign yourself or the merge owner, merge parent PR into `dev`, clean workspaces/worktrees/branches, push to `dev`, and ensure the dev environment contains the code. Conflicts or merge failures return the affected item to `in progress`.
 - `completed` / `Closed`: no execution unless explicitly reopened.
 
 ## Git, Worktree, PR
@@ -58,18 +59,18 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - Unrelated active tasks in `.optima/tasks/current.md` must not block planning; move to/create the correct task worktree instead.
 - Parent setup pulls remote once; after parent branch creation, subtasks can trust the parent local branch without continuous remote polling.
 - Branches: parent `<clickup-task-type>/<parent-task-id>`; subtask `<clickup-task-type>/<parent-task-id>-subtask-<subtask-id>`; pending planned subtasks `<clickup-task-type>/<parent-task-id>-pending-<title-slug>`; PoC always `poc/<clickup-task-id>` and remains there unless productized later.
-- PR targets/start points: subtask -> parent branch and starts from the parent branch; if parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first; parent -> `dev` only after Tech Lead + Validator/QA pass and `CTO`/`PO` move to `merge`; release -> `dev` to `main` only after explicit approval.
+- PR targets/start points: subtask -> parent branch and starts from the parent branch; if parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first; parent -> `dev` only after Tech Lead + Validator/QA pass and a parent-validation human `Approved` comment triggers merge automation; release -> `dev` to `main` only after explicit approval.
 - Preserve user work and unrelated dirty files. Stop and ask if unexpected changes appear.
 
 ## Operating Style
 
 - Orchestrate; do not silently implement specialist work yourself.
 - Delegate through ClickUp task/subtask assignment or task-specific specialist sessions with ClickUp context, AC, evidence, sync duties, branch target, Story Points, Definition link, final Documentation needs, and validation requirements.
-- Never abandon a PM-assigned task: keep working until unblocked and handed off, or post the stop/blocker/clarification/error as a ClickUp comment, remove Workflow/Product Manager, and assign `CTO` plus `PO` or next owner.
+- Never abandon a PM-assigned task: keep working until unblocked and handed off, or post the stop/blocker/clarification/error as a ClickUp comment, remove Workflow/Product Manager, and assign the next delivery owner; assign `CTO`/`PO` only under the human approval allowlist.
 - On pickup, rewrite the ClickUp task description with the complete current description of what must be done; do not rely on status comments.
 - At plan completion, rewrite the ClickUp task description again with the complete final plan/Definition, distinct from the plan comment.
 - Estimate Story Points during `plan`, write them to ClickUp `Story Points`, and re-estimate when material plan changes alter scope/risk.
-- Before assigning `CTO`/`PO` or any next owner, remove the PM assignee and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued.
+- Before assigning any next owner, remove the PM assignee and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued; when the next owner is `CTO`/`PO`, verify the allowlist condition and comment evidence first.
 - Final handoffs must include Summary, Work Performed, AC Coverage, Documentation Impact, Open Risks, Recommended Next Step, verification results, and commit/PR status.
 
 <include:plugin:Agents_Common.md>

package/dist/index.js

@@ -8845,9 +8845,9 @@ var CLICKUP_REQUIRED_SUMMARY_SECTIONS = [
 ];
 var CLICKUP_RAW_LOG_SECTION_NAMES = /* @__PURE__ */ new Set(["Raw Logs", "Logs", "Full Logs", "Command Output", "Transcript"]);
 var CLICKUP_TRANSITIONS = /* @__PURE__ */ new Map([
-  ["plan->in progress", { status: "in progress", assignFinalApprovers: true, comment: "Plan complete; assigning CTO+PO for visibility and moving to implementation." }],
+  ["plan->in progress", { status: "in progress", comment: "Plan complete; moving to implementation without generic CTO/PO assignment." }],
   ["in progress->validation", { status: "validation", comment: "Implementation complete; ready for validation." }],
-  ["validation->merge", { status: "merge", assignFinalApprovers: true, comment: "Validation passed; parent task is ready for CTO+PO merge approval." }],
+  ["validation->merge", { status: "merge", assignFinalApprovers: true, parentOnlyFinalApproval: true, comment: "Parent validation passed with a functional preview URL; ready for CTO/PO approval flow." }],
   ["validation->in progress", { status: "in progress", comment: "Validation failed; returning to implementation." }],
   ["merge->completed", { status: "completed", comment: "Merge complete; closing delivery task." }],
   ["completed->in progress", { status: "in progress", comment: "Task reopened; returning to implementation." }],
@@ -9586,11 +9586,14 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
   const key = `${from}->${to}`;
   const rule = CLICKUP_TRANSITIONS.get(key);
   if (!rule) return { ok: false, dryRun: true, message: `Transition not allowed: ${key}` };
-  const assignsFinalApprovers = rule.assignFinalApprovers === true;
-  const requiresPlanCompletionContract = from === "plan" && assignsFinalApprovers;
+  const assignsFinalApprovers = rule.assignFinalApprovers === true && !(rule.parentOnlyFinalApproval && isSubtask);
+  const requiresPlanCompletionContract = from === "plan" && to === "in progress";
   const definitionContent = compactMarkdownValue(definition);
   const description = compactMarkdownValue(planDescription);
   const validationErrors = [];
+  if (rule.parentOnlyFinalApproval && isSubtask) {
+    validationErrors.push("Subtasks must not use the parent final-approval transition; merge validated subtasks directly into the parent branch/workspace.");
+  }
   if (assignsFinalApprovers && !isRealClickUpAssigneeId(productManagerAssignee) && requireProductManagerAssignee !== false) {
     validationErrors.push("productManagerAssignee must be the configured ClickUp PM assignee ID before assigning final approvers.");
   }
@@ -9599,10 +9602,10 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
   }
   if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
-  const finalApprovers = rule.assignFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
+  const finalApprovers = assignsFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
   const explicitRemovals = (removeAssignees || []).filter(Boolean);
   const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
-  const removalTargets = rule.assignFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
+  const removalTargets = assignsFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
   const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))].filter((assignee) => !removalTargets.includes(assignee));
   const authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
   const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
@@ -9617,7 +9620,7 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
       assignment_delta: {
         add: assigned,
         remove: removalTargets,
-        objective: rule.assignFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
+        objective: assignsFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
       },
       comment: rule.comment,
       description,
@@ -10075,11 +10078,17 @@ function createTestClickUpApiClient(config) {
     __metadata: metadata
   };
 }
-function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
-  const webhook = response?.webhook || response?.data || response || {};
+function clickUpWebhookRemoteInactiveReason(webhook = {}) {
   const healthStatus = String(webhook.health?.status || webhook.health_status || "").trim().toLowerCase();
   const status = String(webhook.status || webhook.state || "").trim().toLowerCase();
-  const active = webhook.active !== false && !["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status) && !["failed", "failing", "unhealthy", "error", "errored", "suspended", "paused"].includes(healthStatus);
+  if (["suspended", "paused", "failed", "failing", "unhealthy", "error", "errored"].includes(healthStatus)) return `remote_health_${healthStatus}`;
+  if (["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status)) return `remote_status_${status}`;
+  if (webhook.active === false) return "remote_inactive";
+  return "";
+}
+function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
+  const webhook = response?.webhook || response?.data || response || {};
+  const active = !clickUpWebhookRemoteInactiveReason(webhook);
   return sanitizeClickUpWebhookState({
     active,
     webhookId: webhook.id || webhook.webhook_id || webhook.webhookId,
@@ -10105,20 +10114,44 @@ function clickUpWebhookLocationCompatible(webhook = {}, config = {}) {
   }
   return true;
 }
+function clickUpWebhookEventsCompatible(webhook = {}, config = {}) {
+  if (!Array.isArray(webhook.events) || webhook.events.length === 0) return false;
+  const actualEvents = new Set(webhook.events);
+  return [...new Set(config?.webhook?.events || [])].every((event) => actualEvents.has(event));
+}
+function clickUpWebhookRemoteCompatibilityReason(webhook = {}, config = {}) {
+  if (!clickUpWebhookLocationCompatible(webhook, config)) return "remote_location_mismatch";
+  if (!clickUpWebhookEventsCompatible(webhook, config)) return "remote_events_mismatch";
+  return "";
+}
+function isClickUpWebhookRemoteSelfHealableReason(reason = "") {
+  const normalized = String(reason || "");
+  return normalized === "remote_inactive" || normalized.startsWith("remote_health_") || normalized.startsWith("remote_status_");
+}
 async function findReusableClickUpWebhook(config, clickupClient = null, existingState = null) {
   if (!clickupClient?.listWebhooks) return null;
   const listed = await clickupClient.listWebhooks({ teamId: config.teamId });
-  let secretlessMatch = null;
+  let incompatibleMatch = null;
   for (const webhook of clickUpWebhookListItems(listed)) {
     const remote = normalizeClickUpWebhookApiResponse(webhook, config);
     if (remote.publicUrl !== config.webhook.publicUrl) continue;
-    if (!clickUpWebhookLocationCompatible(webhook, config)) continue;
+    const compatibilityReason = clickUpWebhookRemoteCompatibilityReason(webhook, config);
+    if (compatibilityReason) {
+      if (compatibilityReason === "remote_events_mismatch" && remote.webhookId && !incompatibleMatch) incompatibleMatch = { ...remote, active: false, reason: compatibilityReason };
+      continue;
+    }
     const existingSecret = existingState?.webhookId === remote.webhookId ? existingState.secret : "";
     const reusable = remote.secret ? remote : { ...remote, secret: existingSecret };
     if (isClickUpWebhookStateActive(reusable, config)) return reusable;
-    if (remote.webhookId && !secretlessMatch) secretlessMatch = { ...remote, active: false, reason: "remote_secret_unavailable" };
+    if (remote.webhookId && !incompatibleMatch) {
+      incompatibleMatch = {
+        ...remote,
+        active: false,
+        reason: remote.active === false ? clickUpWebhookRemoteInactiveReason(webhook) || "remote_inactive" : "remote_secret_unavailable"
+      };
+    }
   }
-  return secretlessMatch;
+  return incompatibleMatch;
 }
 async function validateClickUpWebhookState(state, config, clickupClient = null, { allowRemoteUnhealthyLocalRecovery = false } = {}) {
   if (!isClickUpWebhookStateActive(state, config)) return { valid: false, reason: "state_incomplete" };
@@ -10133,7 +10166,7 @@ async function validateClickUpWebhookState(state, config, clickupClient = null,
     }
     const localStateValidation = await validateClickUpWebhookState(state, config, null);
     if (allowRemoteUnhealthyLocalRecovery && localStateValidation.valid && remote.webhookId === state.webhookId) {
-      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && [...new Set(config.webhook.events || [])].every((event) => new Set(remote.events || []).has(event));
+      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && !clickUpWebhookRemoteCompatibilityReason(match, config);
       if (remoteConfigMatches) {
         return {
           ...localStateValidation,
@@ -10158,12 +10191,18 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
   const { config } = validation;
   const existing = existingState ? sanitizeClickUpWebhookState(existingState, config) : readClickUpWebhookState(worktree, config);
   const existingValidation = await validateClickUpWebhookState(existing, config, clickupClient, { allowRemoteUnhealthyLocalRecovery: true });
-  if (existingValidation.valid) {
+  const canReplaceUnhealthyExisting = existingValidation.mode === "local_state_remote_unhealthy" && existingValidation.remote?.webhookId && clickupClient?.deleteWebhook && clickupClient?.createWebhook;
+  if (existingValidation.valid && !canReplaceUnhealthyExisting) {
     const state = writeClickUpWebhookState(worktree, { ...existingValidation.state, recentEventKeys: existing.recentEventKeys || [] }, config);
     clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: existingValidation.mode });
     return { active: true, valid: true, mode: existingValidation.mode, limitation: existingValidation.limitation, state };
   }
-  const reusableRemote = await findReusableClickUpWebhook(config, clickupClient, existing);
+  const reusableRemote = canReplaceUnhealthyExisting ? {
+    ...existingValidation.remote,
+    active: false,
+    secret: existingValidation.remote.secret || existing.secret,
+    reason: clickUpWebhookRemoteInactiveReason(existingValidation.remote) || existingValidation.reason || "remote_unhealthy_self_heal"
+  } : await findReusableClickUpWebhook(config, clickupClient, existing);
   if (reusableRemote) {
     if (isClickUpWebhookStateActive(reusableRemote, config)) {
       const state = writeClickUpWebhookState(worktree, { ...reusableRemote, recentEventKeys: existing.recentEventKeys || [] }, config);
@@ -10171,10 +10210,31 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
       clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: mode2 });
       return { active: true, valid: true, mode: mode2, state };
     }
-    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
-    return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    if (reusableRemote.active === false && reusableRemote.reason !== "remote_secret_unavailable") {
+      if (!isClickUpWebhookRemoteSelfHealableReason(reusableRemote.reason)) {
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_incompatible" });
+        return { active: false, valid: false, reason: reusableRemote.reason || "remote_incompatible", state: existing, remote: reusableRemote };
+      }
+      if (clickupClient?.deleteWebhook && clickupClient?.createWebhook) {
+        const deleteResult = await deleteClickUpWebhookBestEffort({ webhookId: reusableRemote.webhookId, clickupClient, worktree, reason: reusableRemote.reason || "remote_unhealthy_self_heal" });
+        if (deleteResult.ok) {
+          if (existing.webhookId === reusableRemote.webhookId) markClickUpWebhookInactive(worktree, existing, config);
+        } else {
+          const reason = deleteResult.reason || "remote_unhealthy_delete_failed";
+          clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+          return { active: false, valid: false, reason, state: existing, remote: reusableRemote, deleteResult };
+        }
+      } else {
+        const reason = clickupClient?.deleteWebhook ? "remote_unhealthy_create_unavailable" : "remote_unhealthy_delete_unavailable";
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+        return { active: false, valid: false, reason, state: existing, remote: reusableRemote };
+      }
+    } else {
+      clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
+      return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    }
   }
-  if (existing.webhookId && clickupClient?.deleteWebhook) {
+  if (existing.webhookId && existing.webhookId !== reusableRemote?.webhookId && clickupClient?.deleteWebhook) {
     await deleteClickUpWebhookBestEffort({ webhookId: existing.webhookId, clickupClient, worktree, reason: existingValidation.reason || "startup_self_heal" });
     markClickUpWebhookInactive(worktree, existing, config);
   }

package/dist/sanitize_cli.js

@@ -8852,9 +8852,9 @@ var CLICKUP_REQUIRED_SUMMARY_SECTIONS = [
 ];
 var CLICKUP_RAW_LOG_SECTION_NAMES = /* @__PURE__ */ new Set(["Raw Logs", "Logs", "Full Logs", "Command Output", "Transcript"]);
 var CLICKUP_TRANSITIONS = /* @__PURE__ */ new Map([
-  ["plan->in progress", { status: "in progress", assignFinalApprovers: true, comment: "Plan complete; assigning CTO+PO for visibility and moving to implementation." }],
+  ["plan->in progress", { status: "in progress", comment: "Plan complete; moving to implementation without generic CTO/PO assignment." }],
   ["in progress->validation", { status: "validation", comment: "Implementation complete; ready for validation." }],
-  ["validation->merge", { status: "merge", assignFinalApprovers: true, comment: "Validation passed; parent task is ready for CTO+PO merge approval." }],
+  ["validation->merge", { status: "merge", assignFinalApprovers: true, parentOnlyFinalApproval: true, comment: "Parent validation passed with a functional preview URL; ready for CTO/PO approval flow." }],
   ["validation->in progress", { status: "in progress", comment: "Validation failed; returning to implementation." }],
   ["merge->completed", { status: "completed", comment: "Merge complete; closing delivery task." }],
   ["completed->in progress", { status: "in progress", comment: "Task reopened; returning to implementation." }],
@@ -9593,11 +9593,14 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
   const key = `${from}->${to}`;
   const rule = CLICKUP_TRANSITIONS.get(key);
   if (!rule) return { ok: false, dryRun: true, message: `Transition not allowed: ${key}` };
-  const assignsFinalApprovers = rule.assignFinalApprovers === true;
-  const requiresPlanCompletionContract = from === "plan" && assignsFinalApprovers;
+  const assignsFinalApprovers = rule.assignFinalApprovers === true && !(rule.parentOnlyFinalApproval && isSubtask);
+  const requiresPlanCompletionContract = from === "plan" && to === "in progress";
   const definitionContent = compactMarkdownValue(definition);
   const description = compactMarkdownValue(planDescription);
   const validationErrors = [];
+  if (rule.parentOnlyFinalApproval && isSubtask) {
+    validationErrors.push("Subtasks must not use the parent final-approval transition; merge validated subtasks directly into the parent branch/workspace.");
+  }
   if (assignsFinalApprovers && !isRealClickUpAssigneeId(productManagerAssignee) && requireProductManagerAssignee !== false) {
     validationErrors.push("productManagerAssignee must be the configured ClickUp PM assignee ID before assigning final approvers.");
   }
@@ -9606,10 +9609,10 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
   }
   if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
-  const finalApprovers = rule.assignFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
+  const finalApprovers = assignsFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
   const explicitRemovals = (removeAssignees || []).filter(Boolean);
   const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
-  const removalTargets = rule.assignFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
+  const removalTargets = assignsFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
   const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))].filter((assignee) => !removalTargets.includes(assignee));
   const authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
   const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
@@ -9624,7 +9627,7 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
       assignment_delta: {
         add: assigned,
         remove: removalTargets,
-        objective: rule.assignFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
+        objective: assignsFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
       },
       comment: rule.comment,
       description,
@@ -10082,11 +10085,17 @@ function createTestClickUpApiClient(config) {
     __metadata: metadata
   };
 }
-function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
-  const webhook = response?.webhook || response?.data || response || {};
+function clickUpWebhookRemoteInactiveReason(webhook = {}) {
   const healthStatus = String(webhook.health?.status || webhook.health_status || "").trim().toLowerCase();
   const status = String(webhook.status || webhook.state || "").trim().toLowerCase();
-  const active = webhook.active !== false && !["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status) && !["failed", "failing", "unhealthy", "error", "errored", "suspended", "paused"].includes(healthStatus);
+  if (["suspended", "paused", "failed", "failing", "unhealthy", "error", "errored"].includes(healthStatus)) return `remote_health_${healthStatus}`;
+  if (["inactive", "disabled", "suspended", "failed", "failing", "error", "errored", "paused"].includes(status)) return `remote_status_${status}`;
+  if (webhook.active === false) return "remote_inactive";
+  return "";
+}
+function normalizeClickUpWebhookApiResponse(response = {}, fallbackConfig = null) {
+  const webhook = response?.webhook || response?.data || response || {};
+  const active = !clickUpWebhookRemoteInactiveReason(webhook);
   return sanitizeClickUpWebhookState({
     active,
     webhookId: webhook.id || webhook.webhook_id || webhook.webhookId,
@@ -10112,20 +10121,44 @@ function clickUpWebhookLocationCompatible(webhook = {}, config = {}) {
   }
   return true;
 }
+function clickUpWebhookEventsCompatible(webhook = {}, config = {}) {
+  if (!Array.isArray(webhook.events) || webhook.events.length === 0) return false;
+  const actualEvents = new Set(webhook.events);
+  return [...new Set(config?.webhook?.events || [])].every((event) => actualEvents.has(event));
+}
+function clickUpWebhookRemoteCompatibilityReason(webhook = {}, config = {}) {
+  if (!clickUpWebhookLocationCompatible(webhook, config)) return "remote_location_mismatch";
+  if (!clickUpWebhookEventsCompatible(webhook, config)) return "remote_events_mismatch";
+  return "";
+}
+function isClickUpWebhookRemoteSelfHealableReason(reason = "") {
+  const normalized = String(reason || "");
+  return normalized === "remote_inactive" || normalized.startsWith("remote_health_") || normalized.startsWith("remote_status_");
+}
 async function findReusableClickUpWebhook(config, clickupClient = null, existingState = null) {
   if (!clickupClient?.listWebhooks) return null;
   const listed = await clickupClient.listWebhooks({ teamId: config.teamId });
-  let secretlessMatch = null;
+  let incompatibleMatch = null;
   for (const webhook of clickUpWebhookListItems(listed)) {
     const remote = normalizeClickUpWebhookApiResponse(webhook, config);
     if (remote.publicUrl !== config.webhook.publicUrl) continue;
-    if (!clickUpWebhookLocationCompatible(webhook, config)) continue;
+    const compatibilityReason = clickUpWebhookRemoteCompatibilityReason(webhook, config);
+    if (compatibilityReason) {
+      if (compatibilityReason === "remote_events_mismatch" && remote.webhookId && !incompatibleMatch) incompatibleMatch = { ...remote, active: false, reason: compatibilityReason };
+      continue;
+    }
     const existingSecret = existingState?.webhookId === remote.webhookId ? existingState.secret : "";
     const reusable = remote.secret ? remote : { ...remote, secret: existingSecret };
     if (isClickUpWebhookStateActive(reusable, config)) return reusable;
-    if (remote.webhookId && !secretlessMatch) secretlessMatch = { ...remote, active: false, reason: "remote_secret_unavailable" };
+    if (remote.webhookId && !incompatibleMatch) {
+      incompatibleMatch = {
+        ...remote,
+        active: false,
+        reason: remote.active === false ? clickUpWebhookRemoteInactiveReason(webhook) || "remote_inactive" : "remote_secret_unavailable"
+      };
+    }
   }
-  return secretlessMatch;
+  return incompatibleMatch;
 }
 async function validateClickUpWebhookState(state, config, clickupClient = null, { allowRemoteUnhealthyLocalRecovery = false } = {}) {
   if (!isClickUpWebhookStateActive(state, config)) return { valid: false, reason: "state_incomplete" };
@@ -10140,7 +10173,7 @@ async function validateClickUpWebhookState(state, config, clickupClient = null,
     }
     const localStateValidation = await validateClickUpWebhookState(state, config, null);
     if (allowRemoteUnhealthyLocalRecovery && localStateValidation.valid && remote.webhookId === state.webhookId) {
-      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && [...new Set(config.webhook.events || [])].every((event) => new Set(remote.events || []).has(event));
+      const remoteConfigMatches = remote.publicUrl === config.webhook.publicUrl && !clickUpWebhookRemoteCompatibilityReason(match, config);
       if (remoteConfigMatches) {
         return {
           ...localStateValidation,
@@ -10165,12 +10198,18 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
   const { config } = validation;
   const existing = existingState ? sanitizeClickUpWebhookState(existingState, config) : readClickUpWebhookState(worktree, config);
   const existingValidation = await validateClickUpWebhookState(existing, config, clickupClient, { allowRemoteUnhealthyLocalRecovery: true });
-  if (existingValidation.valid) {
+  const canReplaceUnhealthyExisting = existingValidation.mode === "local_state_remote_unhealthy" && existingValidation.remote?.webhookId && clickupClient?.deleteWebhook && clickupClient?.createWebhook;
+  if (existingValidation.valid && !canReplaceUnhealthyExisting) {
     const state = writeClickUpWebhookState(worktree, { ...existingValidation.state, recentEventKeys: existing.recentEventKeys || [] }, config);
     clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: existingValidation.mode });
     return { active: true, valid: true, mode: existingValidation.mode, limitation: existingValidation.limitation, state };
   }
-  const reusableRemote = await findReusableClickUpWebhook(config, clickupClient, existing);
+  const reusableRemote = canReplaceUnhealthyExisting ? {
+    ...existingValidation.remote,
+    active: false,
+    secret: existingValidation.remote.secret || existing.secret,
+    reason: clickUpWebhookRemoteInactiveReason(existingValidation.remote) || existingValidation.reason || "remote_unhealthy_self_heal"
+  } : await findReusableClickUpWebhook(config, clickupClient, existing);
   if (reusableRemote) {
     if (isClickUpWebhookStateActive(reusableRemote, config)) {
       const state = writeClickUpWebhookState(worktree, { ...reusableRemote, recentEventKeys: existing.recentEventKeys || [] }, config);
@@ -10178,10 +10217,31 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
       clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: mode2 });
       return { active: true, valid: true, mode: mode2, state };
     }
-    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
-    return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    if (reusableRemote.active === false && reusableRemote.reason !== "remote_secret_unavailable") {
+      if (!isClickUpWebhookRemoteSelfHealableReason(reusableRemote.reason)) {
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_incompatible" });
+        return { active: false, valid: false, reason: reusableRemote.reason || "remote_incompatible", state: existing, remote: reusableRemote };
+      }
+      if (clickupClient?.deleteWebhook && clickupClient?.createWebhook) {
+        const deleteResult = await deleteClickUpWebhookBestEffort({ webhookId: reusableRemote.webhookId, clickupClient, worktree, reason: reusableRemote.reason || "remote_unhealthy_self_heal" });
+        if (deleteResult.ok) {
+          if (existing.webhookId === reusableRemote.webhookId) markClickUpWebhookInactive(worktree, existing, config);
+        } else {
+          const reason = deleteResult.reason || "remote_unhealthy_delete_failed";
+          clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+          return { active: false, valid: false, reason, state: existing, remote: reusableRemote, deleteResult };
+        }
+      } else {
+        const reason = clickupClient?.deleteWebhook ? "remote_unhealthy_create_unavailable" : "remote_unhealthy_delete_unavailable";
+        clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason });
+        return { active: false, valid: false, reason, state: existing, remote: reusableRemote };
+      }
+    } else {
+      clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_preserved", webhookId: reusableRemote.webhookId, reason: reusableRemote.reason || "remote_webhook_exists_without_secret" });
+      return { active: false, valid: false, reason: reusableRemote.reason || "remote_webhook_exists_without_secret", state: existing, remote: reusableRemote };
+    }
   }
-  if (existing.webhookId && clickupClient?.deleteWebhook) {
+  if (existing.webhookId && existing.webhookId !== reusableRemote?.webhookId && clickupClient?.deleteWebhook) {
     await deleteClickUpWebhookBestEffort({ webhookId: existing.webhookId, clickupClient, worktree, reason: existingValidation.reason || "startup_self_heal" });
     markClickUpWebhookInactive(worktree, existing, config);
   }

package/docs/core/agent_orchestration.md

@@ -22,7 +22,8 @@
 - `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.
-- 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.
+- 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, external tools, or access; or parent `validation` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask planning/validation, or partial-phase stops.
 - 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.
 - Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, stores new `ses_...` ids in ClickUp `agent_metadata`, and reports stale/missing sessions to ClickUp without creating replacements.
@@ -35,8 +36,8 @@
 - Parent task start pulls remote once; after branch creation, subtasks trust the parent local branch instead of continuous remote polling.
 - Parent branch format is `<clickup-task-type>/<parent-task-id>`; subtask branch format is the non-nested sibling ref `<clickup-task-type>/<parent-task-id>-subtask-<subtask-id>`; pending planned subtasks use `<clickup-task-type>/<parent-task-id>-pending-<title-slug>`; PoC branch format is always `poc/<clickup-task-id>` and stays there until a later productization task.
 - Subtask worktrees start from the parent branch and PR to the parent branch; if the parent branch/worktree is missing, bootstrap the parent from `dev`/`origin/dev` first. Parent task PRs target `dev`, and release PRs target `main` from `dev` only after explicit approval.
-- After successful subtask validation, Validator/QA merges the subtask PR into the parent branch/workspace without `CTO`/`PO` approval.
-- After parent Tech Lead and Validator/QA validation passes, the parent task stays in `validation`, `CTO`/`PO` are assigned and marked as approval owners, and they approve by moving it to `merge`; only then does Validator/QA attempt the parent PR merge into `dev`.
+- After successful subtask validation, Validator/QA merges the subtask PR into the parent branch/workspace without `CTO`/`PO` assignment or approval.
+- After parent Tech Lead and Validator/QA validation passes, the parent task may assign `CTO`/`PO` only when a functional validation URL is provided; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges the parent PR into `dev`, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code.
 - If any subtask or parent merge conflicts or fails, Validator/QA returns the affected ClickUp item to `in progress` and routes it to the coding owner.
 - Never push directly to `main`.
 - `investigation` and `spec` tasks may run in parallel only when they avoid conflicting delivery artifacts.

package/docs/core/agent_orchestration.prompt.md

@@ -14,7 +14,7 @@
 - `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.
-- 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.
+- 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, or parent `validation` with a functional preview URL. 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 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.
 - Store `agent_metadata` session JSON; `Definition` is the plan contract, final Documentation is delivered behavior docs.

package/docs/core/role_contracts.md

@@ -21,8 +21,9 @@
 - 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.
-- 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`.
+- Human approval assignment is prohibited except for three cases: parent `plan` with clear ClickUp-commented questions, `in progress` blockers caused by missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask work, or partial-phase stops.
+- 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, 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 environment contains the code.
 - 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.
 - Git authority follows ClickUp-first rules: principal workspace on `dev`, no direct `main` push, parent task pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs from `dev` to `main` only after approval.
 

package/docs/core/role_contracts.prompt.md

@@ -15,8 +15,9 @@
 - 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.
-- 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`.
+- Human approval assignment is prohibited except for parent `plan` questions with clear ClickUp comments, `in progress` blockers from missing credentials/tools/access, or parent `validation` with a functional preview URL; never use it for generic handoff, cleanup, subtasks, or phase stops.
+- 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 human comments `Approved`, automation removes human assignees, assigns merge owner/self, merges to `dev`, cleans workspaces/worktrees/branches, pushes, and ensures dev receives the code.
 - Failed or conflicted subtask/parent merges return the affected ClickUp item to `in progress` for the coding owner.
 - ClickUp-first Git rules: principal workspace on `dev`, no direct `main` push, parent pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs `dev` -> `main` only after approval.
 - BA owns product truth and product-facing feature/domain docs.

package/docs/core/task_model.md

@@ -12,9 +12,16 @@
 - 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.
-- 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.
+- 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`.
 
+## Human Approval Allowlist
+
+- 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, external tools, or access. 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 with a functional preview URL such as `https://<taskid>-preview.defend.tech` or an equivalent working validation 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 environment contains the code.
+
 ## Routing Rules
 
 - `tiny` stays within one slice and usually one specialist handoff.
@@ -24,7 +31,7 @@
 - While one shared-worktree implementation task is active, parallel work is limited to non-conflicting `investigation` or `spec`.
 - WPM estimates `Story Points` during `plan`, re-estimates on material plan changes, links the `Definition` plan contract when needed, and records `agent_metadata` session IDs.
 - In ClickUp-first mode, work should be decomposed into parent/subtask branches: parent tasks pull remote once at start, parent branches use `<type>/<parent-id>` and merge to `dev`, subtasks use non-nested `<type>/<parent-id>-subtask-<subtask-id>` branches that start from/trust the parent local branch and merge to parent branches, missing parent branches/worktrees are bootstrapped from `dev`/`origin/dev` before subtask worktree creation, PoC branches stay `poc/<clickup-task-id>`, and release branches merge `dev` to `main` only after approval.
-- Validator/QA owns merge execution after the correct gate: validated subtask PRs merge directly into the parent branch/workspace, while parent PRs merge into `dev` only after `CTO`/`PO` move the parent task to `merge`. Merge conflicts or failed attempts return the affected task/subtask to `in progress` for the coding owner.
+- Validator/QA owns merge execution after the correct gate: validated subtask PRs merge directly into the parent branch/workspace without CTO/PO assignment, while parent PRs merge into `dev` only after the parent validation approval allowlist is satisfied and a human `Approved` comment triggers merge automation. Merge conflicts or failed attempts return the affected task/subtask to `in progress` for the coding owner.
 
 ## Pre-Sync Defaults
 

package/docs/core/task_model.prompt.md

@@ -7,7 +7,7 @@
 - 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`, 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.
+- 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, or parent `validation` with a functional preview URL. 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 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

@@ -19,7 +19,8 @@ We adhere to a strict test pyramid strategy to ensure 100% reliability.
 - **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.
-- **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.
+- **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, or parent `validation` with a functional preview URL. Never assign them for generic handoff, routine validation, cleanup, subtasks, or partial-phase stops.
+- **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.
 - **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.
 - **Investigation Outputs:** `investigation` tasks should produce findings, reproduction notes, logs when useful, and a recommended next step rather than pretending to be implementation tests.

package/package.json

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