@defend-tech/opencode-optima 0.1.60 → 0.1.62

package/dist/sanitize_cli.js

@@ -8534,6 +8534,7 @@ var CLICKUP_WEBHOOK_REQUEST_TIMEOUT_MS = 1e4;
 var CLICKUP_WEBHOOK_STARTUP_TASK_LIMIT = 50;
 var CLICKUP_WEBHOOK_STARTUP_COMMENT_LIMIT = 100;
 var CLICKUP_WEBHOOK_STARTUP_RECONCILIATION_DELAY_MS = 3e4;
+var CLICKUP_WORKTREE_FAILURE_COMMENT_DEDUPE_MS = 10 * 60 * 1e3;
 var CLICKUP_WEBHOOK_LOG_LEVELS = /* @__PURE__ */ new Set(["error", "info", "verbose"]);
 var CLICKUP_WEBHOOK_REDACTED = "[REDACTED]";
 var DISCUSSION_BACKFILL_FETCH_LIMIT = 100;
@@ -8851,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." }],
@@ -9241,30 +9242,36 @@ function openChamberUrl(baseUrl, pathname, query = {}) {
   }
   return url.toString();
 }
-async function readOpenChamberJson(response, endpoint) {
+async function readOpenChamberJson(response, endpoint, serviceName = "OpenChamber") {
   const text = await response.text();
   let data = null;
   if (text.trim()) {
     try {
       data = JSON.parse(text);
     } catch {
-      throw new Error(`OpenChamber ${endpoint} returned non-JSON response.`);
+      throw new Error(`${serviceName} ${endpoint} returned non-JSON response.`);
     }
   }
   if (!response.ok) {
     const message = data?.error?.message || data?.message || data?.data?.message || text.slice(0, 200) || `HTTP ${response.status}`;
-    throw new Error(`OpenChamber ${endpoint} failed: ${response.status} ${message}`);
+    throw new Error(`${serviceName} ${endpoint} failed: ${response.status} ${message}`);
   }
   return data;
 }
-async function requestOpenChamberJson({ baseUrl, endpoint, method = "GET", directory, body, fetchImpl = globalThis.fetch } = {}) {
-  if (typeof fetchImpl !== "function") throw new Error("OpenChamber worktree provisioning requires fetch.");
+async function requestServiceJson({ baseUrl, serviceName = "OpenChamber", endpoint, method = "GET", directory, body, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== "function") throw new Error(`${serviceName} API calls require fetch.`);
   const response = await fetchImpl(openChamberUrl(baseUrl, endpoint, { directory }), {
     method,
     headers: body ? { "content-type": "application/json" } : void 0,
     body: body ? JSON.stringify(body) : void 0
   });
-  return readOpenChamberJson(response, endpoint);
+  return readOpenChamberJson(response, endpoint, serviceName);
+}
+async function requestOpenChamberJson(options = {}) {
+  return requestServiceJson({ ...options, serviceName: "OpenChamber" });
+}
+async function requestOpenCodeJson(options = {}) {
+  return requestServiceJson({ ...options, serviceName: "OpenCode" });
 }
 function normalizeOpenChamberCollection(value) {
   if (Array.isArray(value)) return value;
@@ -9303,39 +9310,40 @@ function openChamberListIncludesBranch(list, directory, branch) {
     return !entryBranch || entryBranch === branch;
   });
 }
-async function findOpenChamberProject({ baseUrl, baseWorktree, fetchImpl = globalThis.fetch } = {}) {
-  const projects = await requestOpenChamberJson({ baseUrl, endpoint: "/project", directory: baseWorktree, fetchImpl });
+async function findOpenChamberProject({ opencodeBaseUrl, baseWorktree, fetchImpl = globalThis.fetch } = {}) {
+  const projects = await requestOpenCodeJson({ baseUrl: opencodeBaseUrl, endpoint: "/project", directory: baseWorktree, fetchImpl });
   if (!Array.isArray(projects)) return null;
   const resolvedBase = path5.resolve(baseWorktree);
   return projects.find((project) => path5.resolve(String(project?.worktree || project?.path || "")) === resolvedBase) || null;
 }
-async function refreshOpenChamberProjectCopy({ baseUrl, baseWorktree, projectId, fetchImpl = globalThis.fetch } = {}) {
+async function refreshOpenChamberProjectCopy({ opencodeBaseUrl, projectId, fetchImpl = globalThis.fetch } = {}) {
   if (!projectId) return { refreshed: false, reason: "project_id_unavailable" };
-  const response = await fetchImpl(openChamberUrl(baseUrl, `/experimental/project/${encodeURIComponent(projectId)}/copy/refresh`, {}), { method: "POST" });
-  await readOpenChamberJson(response, "/experimental/project/{projectID}/copy/refresh");
+  await requestOpenCodeJson({ baseUrl: opencodeBaseUrl, endpoint: `/experimental/project/${encodeURIComponent(projectId)}/copy/refresh`, method: "POST", fetchImpl });
   return { refreshed: true, projectId };
 }
-async function listOpenChamberGitWorktrees({ baseUrl, baseWorktree, fetchImpl = globalThis.fetch } = {}) {
-  return requestOpenChamberJson({ baseUrl, endpoint: "/api/git/worktrees", directory: baseWorktree, fetchImpl });
+async function listOpenChamberGitWorktrees({ openchamberBaseUrl, baseUrl, baseWorktree, fetchImpl = globalThis.fetch } = {}) {
+  return requestOpenChamberJson({ baseUrl: openchamberBaseUrl || baseUrl, endpoint: "/api/git/worktrees", directory: baseWorktree, fetchImpl });
 }
-async function verifyOpenChamberGitWorktree({ baseUrl, baseWorktree, worktreePath, branch, fetchImpl = globalThis.fetch } = {}) {
-  const worktrees = await listOpenChamberGitWorktrees({ baseUrl, baseWorktree, fetchImpl });
+async function verifyOpenChamberGitWorktree({ openchamberBaseUrl, baseUrl, baseWorktree, worktreePath, branch, fetchImpl = globalThis.fetch } = {}) {
+  const worktrees = await listOpenChamberGitWorktrees({ openchamberBaseUrl: openchamberBaseUrl || baseUrl, baseWorktree, fetchImpl });
   const verified = openChamberListIncludesBranch(worktrees, worktreePath, branch);
   if (!verified) {
     throw new Error(`OpenChamber Git worktree verification failed for ${worktreePath} on ${branch}.`);
   }
   return { worktree: true, branch: true };
 }
-async function syncOpenChamberWorktreeVisibility({ baseUrl, baseWorktree, worktreePath, branch, fetchImpl = globalThis.fetch } = {}) {
-  const gitWorktree = await verifyOpenChamberGitWorktree({ baseUrl, baseWorktree, worktreePath, branch, fetchImpl });
-  await requestOpenChamberJson({ baseUrl, endpoint: "/experimental/workspace/sync-list", method: "POST", directory: baseWorktree, fetchImpl });
-  const project = await findOpenChamberProject({ baseUrl, baseWorktree, fetchImpl });
-  if (!project?.id) throw new Error("OpenChamber project was not found after workspace sync; refusing to treat worktree as visible.");
-  await refreshOpenChamberProjectCopy({ baseUrl, baseWorktree, projectId: project.id, fetchImpl });
+async function syncOpenChamberWorktreeVisibility({ openchamberBaseUrl, opencodeBaseUrl, baseUrl, baseWorktree, worktreePath, branch, fetchImpl = globalThis.fetch } = {}) {
+  const effectiveOpenChamberBaseUrl = openchamberBaseUrl || baseUrl;
+  const effectiveOpenCodeBaseUrl = opencodeBaseUrl || baseUrl;
+  const gitWorktree = await verifyOpenChamberGitWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, baseWorktree, worktreePath, branch, fetchImpl });
+  await requestOpenCodeJson({ baseUrl: effectiveOpenCodeBaseUrl, endpoint: "/experimental/workspace/sync-list", method: "POST", directory: baseWorktree, fetchImpl });
+  const project = await findOpenChamberProject({ opencodeBaseUrl: effectiveOpenCodeBaseUrl, baseWorktree, fetchImpl });
+  if (!project?.id) throw new Error("OpenCode project was not found after workspace sync; refusing to treat worktree as visible.");
+  await refreshOpenChamberProjectCopy({ opencodeBaseUrl: effectiveOpenCodeBaseUrl, projectId: project.id, fetchImpl });
   const [worktrees, workspaces, directories] = await Promise.all([
-    listOpenChamberGitWorktrees({ baseUrl, baseWorktree, fetchImpl }),
-    requestOpenChamberJson({ baseUrl, endpoint: "/experimental/workspace", directory: baseWorktree, fetchImpl }),
-    requestOpenChamberJson({ baseUrl, endpoint: `/project/${encodeURIComponent(project.id)}/directories`, directory: baseWorktree, fetchImpl })
+    listOpenChamberGitWorktrees({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, baseWorktree, fetchImpl }),
+    requestOpenCodeJson({ baseUrl: effectiveOpenCodeBaseUrl, endpoint: "/experimental/workspace", directory: baseWorktree, fetchImpl }),
+    requestOpenCodeJson({ baseUrl: effectiveOpenCodeBaseUrl, endpoint: `/project/${encodeURIComponent(project.id)}/directories`, directory: baseWorktree, fetchImpl })
   ]);
   const visibility = {
     worktree: openChamberListIncludesBranch(worktrees, worktreePath, branch),
@@ -9345,7 +9353,7 @@ async function syncOpenChamberWorktreeVisibility({ baseUrl, baseWorktree, worktr
     projectId: project.id
   };
   if (!visibility.worktree || !visibility.workspace || !visibility.projectDirectory) {
-    throw new Error(`OpenChamber visibility verification failed for ${worktreePath}: ${JSON.stringify(visibility)}`);
+    throw new Error(`OpenCode visibility verification failed for ${worktreePath}: ${JSON.stringify(visibility)}`);
   }
   return visibility;
 }
@@ -9354,12 +9362,13 @@ function assertOpenChamberClickUpWorktreePath({ baseWorktree, worktreePath } = {
     throw new Error(`OpenChamber worktree path is outside the configured ClickUp sibling scope: ${worktreePath}`);
   }
 }
-async function createOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch, worktreePath, startPoint, branchExists = false, fetchImpl = globalThis.fetch } = {}) {
+async function createOpenChamberClickUpWorktree({ openchamberBaseUrl, baseUrl, baseWorktree, branch, worktreePath, startPoint, branchExists = false, fetchImpl = globalThis.fetch } = {}) {
+  const effectiveOpenChamberBaseUrl = openchamberBaseUrl || baseUrl;
   const worktreeName = clickUpOpenChamberWorktreeName(branch);
   const body = { name: worktreeName, mode: branchExists ? "existing" : "new", worktreeName, branchName: branch, startRef: branchExists ? branch : startPoint };
   let created;
   try {
-    created = await requestOpenChamberJson({ baseUrl, endpoint: "/api/git/worktrees", method: "POST", directory: baseWorktree, body, fetchImpl });
+    created = await requestOpenChamberJson({ baseUrl: effectiveOpenChamberBaseUrl, endpoint: "/api/git/worktrees", method: "POST", directory: baseWorktree, body, fetchImpl });
   } catch (error) {
     throw new Error(`OpenChamber could not create ${branch} from ${branchExists ? branch : startPoint}; API may not support required branch/startRef semantics. Fail-closed: ${error.message}`);
   }
@@ -9371,15 +9380,17 @@ async function createOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch,
   if (createdBranch !== branch) {
     throw new Error(`OpenChamber created unexpected branch ${createdBranch || "<unknown>"}; expected ${branch}.`);
   }
-  const verified = await verifyOpenChamberGitWorktree({ baseUrl, baseWorktree, worktreePath: createdDirectory, branch, fetchImpl });
+  const verified = await verifyOpenChamberGitWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, baseWorktree, worktreePath: createdDirectory, branch, fetchImpl });
   return { created, worktree: path5.resolve(createdDirectory), branch: createdBranch, verified };
 }
-async function registerOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch, worktreePath, fetchImpl = globalThis.fetch, source = "reuse" } = {}) {
+async function registerOpenChamberClickUpWorktree({ openchamberBaseUrl, opencodeBaseUrl, baseUrl, baseWorktree, branch, worktreePath, fetchImpl = globalThis.fetch, source = "reuse" } = {}) {
   assertOpenChamberClickUpWorktreePath({ baseWorktree, worktreePath });
-  const visibility = await syncOpenChamberWorktreeVisibility({ baseUrl, baseWorktree, worktreePath, branch, fetchImpl });
+  const visibility = await syncOpenChamberWorktreeVisibility({ openchamberBaseUrl: openchamberBaseUrl || baseUrl, opencodeBaseUrl: opencodeBaseUrl || baseUrl, baseWorktree, worktreePath, branch, fetchImpl });
   return { branch, worktree: path5.resolve(worktreePath), reused: true, provider: "openchamber", openChamber: { source, visibility } };
 }
-async function ensureClickUpTaskWorktreeOpenChamber({ baseWorktree = "", taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", existingMetadata = {}, runGitFn = runGit, baseUrl = "", fetchImpl = globalThis.fetch, log = null } = {}) {
+async function ensureClickUpTaskWorktreeOpenChamber({ baseWorktree = "", taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", existingMetadata = {}, runGitFn = runGit, openchamberBaseUrl = "", opencodeBaseUrl = "", baseUrl = "", fetchImpl = globalThis.fetch, log = null } = {}) {
+  const effectiveOpenChamberBaseUrl = openchamberBaseUrl || baseUrl;
+  const effectiveOpenCodeBaseUrl = opencodeBaseUrl || baseUrl;
   const effectiveParent = parentTaskId || taskId;
   const isSubtask = isClickUpSubtaskRoute({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
   const parentBranch = isSubtask ? deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent }) : "";
@@ -9387,13 +9398,13 @@ async function ensureClickUpTaskWorktreeOpenChamber({ baseWorktree = "", taskId,
   const prTarget = parentBranch || "dev";
   const existing = safeExistingClickUpWorktree({ metadata: existingMetadata, branch });
   if (existing) {
-    const registered = await registerOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch, worktreePath: existing.worktree, fetchImpl, source: "metadata_reuse" });
+    const registered = await registerOpenChamberClickUpWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, opencodeBaseUrl: effectiveOpenCodeBaseUrl, baseWorktree, branch, worktreePath: existing.worktree, fetchImpl, source: "metadata_reuse" });
     log?.({ type: "openchamber_worktree_registered", taskId, branch, worktree: registered.worktree, source: "metadata_reuse", visibility: registered.openChamber.visibility });
     return { ...registered, parentBranch: parentBranch || void 0, prTarget };
   }
   const worktreePath = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
   if (fs5.existsSync(worktreePath)) {
-    const registered = await registerOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch, worktreePath, fetchImpl, source: "existing_directory" });
+    const registered = await registerOpenChamberClickUpWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, opencodeBaseUrl: effectiveOpenCodeBaseUrl, baseWorktree, branch, worktreePath, fetchImpl, source: "existing_directory" });
     log?.({ type: "openchamber_worktree_registered", taskId, branch, worktree: registered.worktree, source: "existing_directory", visibility: registered.openChamber.visibility });
     return { ...registered, parentBranch: parentBranch || void 0, prTarget };
   }
@@ -9401,40 +9412,54 @@ async function ensureClickUpTaskWorktreeOpenChamber({ baseWorktree = "", taskId,
   if (isSubtask) {
     const parentWorktree = deriveClickUpWorktree({ baseWorktree, taskId: effectiveParent, taskType, parentTaskId: effectiveParent });
     if (fs5.existsSync(parentWorktree)) {
-      const registeredParent = await registerOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch: parentBranch, worktreePath: parentWorktree, fetchImpl, source: "parent_existing_directory" });
+      const registeredParent = await registerOpenChamberClickUpWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, opencodeBaseUrl: effectiveOpenCodeBaseUrl, baseWorktree, branch: parentBranch, worktreePath: parentWorktree, fetchImpl, source: "parent_existing_directory" });
       parentBootstrap = { branch: parentBranch, worktree: registeredParent.worktree, reused: true, provider: "openchamber", visibility: registeredParent.openChamber.visibility };
     } else {
       const parentStartPoint = resolveClickUpDevStartPoint(baseWorktree, runGitFn);
       const parentBranchExists = clickUpGitRefExists(baseWorktree, parentBranch, runGitFn);
-      const createdParent = await createOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch: parentBranch, worktreePath: parentWorktree, startPoint: parentStartPoint, branchExists: parentBranchExists, fetchImpl });
-      const parentVisibility = await syncOpenChamberWorktreeVisibility({ baseUrl, baseWorktree, worktreePath: createdParent.worktree, branch: parentBranch, fetchImpl });
+      const createdParent = await createOpenChamberClickUpWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, baseWorktree, branch: parentBranch, worktreePath: parentWorktree, startPoint: parentStartPoint, branchExists: parentBranchExists, fetchImpl });
+      const parentVisibility = await syncOpenChamberWorktreeVisibility({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, opencodeBaseUrl: effectiveOpenCodeBaseUrl, baseWorktree, worktreePath: createdParent.worktree, branch: parentBranch, fetchImpl });
       parentBootstrap = { branch: parentBranch, worktree: createdParent.worktree, startPoint: parentBranchExists ? parentBranch : parentStartPoint, reused: parentBranchExists, provider: "openchamber", visibility: parentVisibility };
       log?.({ type: "openchamber_worktree_created", taskId: effectiveParent, branch: parentBranch, worktree: parentBootstrap.worktree, startPoint: parentBootstrap.startPoint, visibility: parentVisibility });
     }
   }
   const startPoint = isSubtask ? parentBranch : resolveClickUpDevStartPoint(baseWorktree, runGitFn);
   const branchExists = clickUpGitRefExists(baseWorktree, branch, runGitFn);
-  const created = await createOpenChamberClickUpWorktree({ baseUrl, baseWorktree, branch, worktreePath, startPoint, branchExists, fetchImpl });
-  const visibility = await syncOpenChamberWorktreeVisibility({ baseUrl, baseWorktree, worktreePath: created.worktree, branch, fetchImpl });
+  const created = await createOpenChamberClickUpWorktree({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, baseWorktree, branch, worktreePath, startPoint, branchExists, fetchImpl });
+  const visibility = await syncOpenChamberWorktreeVisibility({ openchamberBaseUrl: effectiveOpenChamberBaseUrl, opencodeBaseUrl: effectiveOpenCodeBaseUrl, baseWorktree, worktreePath: created.worktree, branch, fetchImpl });
   log?.({ type: "openchamber_worktree_created", taskId, branch, worktree: created.worktree, startPoint: branchExists ? branch : startPoint, visibility });
   return { branch, worktree: created.worktree, reused: false, startPoint, parentBranch: parentBranch || void 0, prTarget, parentBootstrap: parentBootstrap || void 0, provider: "openchamber", openChamber: { source: "created", visibility } };
 }
 async function ensureClickUpTaskWorktreeForWebhook({ opencodeBaseUrl = "", opencodeBaseUrlConfigured = false, openchamberBaseUrl = "", openchamberBaseUrlConfigured = false, clickupClient = null, webhookWorktree = process.cwd(), fetchImpl = globalThis.fetch, ...options } = {}) {
-  void opencodeBaseUrl;
   void opencodeBaseUrlConfigured;
   if (!openchamberBaseUrlConfigured || !openchamberBaseUrl) return ensureClickUpTaskWorktree(options);
   try {
-    return await ensureClickUpTaskWorktreeOpenChamber({ ...options, baseUrl: openchamberBaseUrl, fetchImpl, log: (entry) => appendClickUpWebhookLocalLog(webhookWorktree, entry) });
+    return await ensureClickUpTaskWorktreeOpenChamber({ ...options, openchamberBaseUrl, opencodeBaseUrl, fetchImpl, log: (entry) => appendClickUpWebhookLocalLog(webhookWorktree, entry) });
   } catch (error) {
     const message = `OpenChamber worktree provisioning failed for ${options.taskId || "unknown task"}; raw git fallback is disabled to avoid invisible worktrees. ${error.message}`;
     appendClickUpWebhookLocalLog(webhookWorktree, { type: "openchamber_worktree_failed", taskId: options.taskId || null, message });
     if (typeof clickupClient?.postTaskComment === "function") {
-      try {
-        await clickupClient.postTaskComment({ taskId: options.taskId, comment: `${message}
+      const taskId = options.taskId || "unknown task";
+      const ledgerPath = clickUpCommentLedgerPath(webhookWorktree);
+      const comment = `${message}
 
-Optima did not run raw git worktree fallback. Please verify clickup.openchamber.base_url and OpenChamber Git API compatibility.` });
-      } catch (commentError) {
-        appendClickUpWebhookLocalLog(webhookWorktree, { type: "openchamber_worktree_blocker_comment_failed", taskId: options.taskId || null, message: commentError.message });
+Optima did not run raw git worktree fallback. Please verify clickup.openchamber.base_url and OpenCode/OpenChamber endpoint configuration.`;
+      let dedupe = { post: true, key: clickUpWorktreeFailureCommentKey({ taskId, message }) };
+      try {
+        dedupe = shouldPostClickUpWorktreeFailureComment({ ledgerPath, taskId, message });
+      } catch (ledgerError) {
+        appendClickUpWebhookLocalLog(webhookWorktree, { type: "openchamber_worktree_comment_dedupe_failed", taskId, message: ledgerError.message });
+      }
+      if (dedupe.post) {
+        try {
+          await clickupClient.postTaskComment({ taskId: options.taskId, comment });
+          recordClickUpWorktreeFailureComment({ ledgerPath, taskId, message, posted: true });
+        } catch (commentError) {
+          appendClickUpWebhookLocalLog(webhookWorktree, { type: "openchamber_worktree_blocker_comment_failed", taskId: options.taskId || null, message: commentError.message });
+        }
+      } else {
+        appendClickUpWebhookLocalLog(webhookWorktree, { type: "openchamber_worktree_blocker_comment_deduped", taskId, key: dedupe.key, reason: dedupe.reason });
+        recordClickUpWorktreeFailureComment({ ledgerPath, taskId, message, posted: false, skippedReason: dedupe.reason });
       }
     }
     throw new Error(message);
@@ -9568,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.");
   }
@@ -9581,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) } : {};
@@ -9599,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,
@@ -10057,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,
@@ -10087,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" };
@@ -10115,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,
@@ -10140,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);
@@ -10153,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);
   }
@@ -10234,23 +10319,29 @@ function rememberClickUpWebhookEvent(state = {}, eventKey, limit = 200) {
   if (recent.includes(eventKey)) return { duplicate: true, state };
   return { duplicate: false, state: { ...state, recentEventKeys: [...recent, eventKey].slice(-limit) } };
 }
-function readClickUpCommentLedger(ledgerPath) {
-  const processed = /* @__PURE__ */ new Set();
-  if (!ledgerPath || !fs5.existsSync(ledgerPath)) return processed;
+function readClickUpCommentLedgerEntries(ledgerPath) {
+  if (!ledgerPath || !fs5.existsSync(ledgerPath)) return [];
   try {
     const raw = fs5.readFileSync(ledgerPath, "utf8");
+    const entries = [];
     for (const [index, line] of raw.split(/\r?\n/).entries()) {
       if (!line.trim()) continue;
       try {
-        const entry = JSON.parse(line);
-        if (entry?.key) processed.add(String(entry.key));
+        entries.push(JSON.parse(line));
       } catch (error) {
         throw new Error(`malformed ledger row ${index + 1}: ${error.message}`);
       }
     }
+    return entries;
   } catch (error) {
     throw new Error(`ClickUp comment ledger unavailable: ${error.message}`);
   }
+}
+function readClickUpCommentLedger(ledgerPath) {
+  const processed = /* @__PURE__ */ new Set();
+  for (const entry of readClickUpCommentLedgerEntries(ledgerPath)) {
+    if (entry?.key) processed.add(String(entry.key));
+  }
   return processed;
 }
 function appendClickUpCommentLedgerEntry(ledgerPath, entry = {}) {
@@ -10316,6 +10407,35 @@ function recordClickUpCommentVersionProcessed({ ledgerPath, key, taskId, eventTy
     recordedAt: at.toISOString()
   });
 }
+function clickUpWorktreeFailureCommentKey({ taskId, message } = {}) {
+  const hash = crypto.createHash("sha256").update(String(message || "")).digest("hex").slice(0, 16);
+  return [String(taskId || "unknown").trim() || "unknown", "worktree_failure", hash].join(":");
+}
+function shouldPostClickUpWorktreeFailureComment({ ledgerPath, taskId, message, now = /* @__PURE__ */ new Date(), windowMs = CLICKUP_WORKTREE_FAILURE_COMMENT_DEDUPE_MS } = {}) {
+  const key = clickUpWorktreeFailureCommentKey({ taskId, message });
+  const nowMs = now instanceof Date ? now.getTime() : new Date(now).getTime();
+  for (const entry of readClickUpCommentLedgerEntries(ledgerPath).reverse()) {
+    if (entry?.key !== key) continue;
+    const postedAtMs = new Date(entry.postedAt || entry.recordedAt || entry.at || 0).getTime();
+    if (Number.isFinite(postedAtMs) && Number.isFinite(nowMs) && nowMs - postedAtMs <= windowMs) {
+      return { post: false, key, reason: "recent_duplicate" };
+    }
+    if (entry?.message === message) return { post: false, key, reason: "latest_equivalent" };
+  }
+  return { post: true, key };
+}
+function recordClickUpWorktreeFailureComment({ ledgerPath, taskId, message, posted = true, skippedReason = null, at = /* @__PURE__ */ new Date() } = {}) {
+  appendClickUpCommentLedgerEntry(ledgerPath, {
+    key: clickUpWorktreeFailureCommentKey({ taskId, message }),
+    taskId,
+    eventType: "worktree_failure",
+    action: posted ? "worktree_failure_comment_posted" : "worktree_failure_comment_skipped",
+    message,
+    posted,
+    skippedReason,
+    postedAt: at.toISOString()
+  });
+}
 function clickUpTaskIdFromPayload(payload = {}) {
   return String(payload.task_id || payload.taskId || payload.task?.id || payload.task?.task_id || "").trim();
 }

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.