@defend-tech/opencode-optima 0.1.71 → 0.1.72

package/assets/agents/workflow_product_manager.md

@@ -45,8 +45,9 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - `backlog`: ignore until prioritized.
 - `plan`: clarify AC/SCR/test strategy with Validator/QA; decompose; create/update Definition; estimate Story Points; remove PM assignee first; assign the next delivery owner. Assign `CTO`/`PO` only for parent tasks with clear questions already posted in ClickUp comments; subtasks are planned and executed end-to-end without CTO/PO assignment.
 - `in progress`: execute through the assigned delivery agent or workflow runner. Treat blockers as work to solve first: spawn or resume Coder for code/build/dependency failures, QA for validation/test/evidence failures, Tech Lead for architecture/review/merge failures, and the relevant specialist for domain blockers. Escalate to `CTO`/`PO` only when genuinely blocked by missing credentials, permissions, external tools, or access after local/subagent resolution attempts; do not stop with phase language such as "I reached phase 1" or "no non-human assignee is available".
-- `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`.
+- `validation`: before moving any task/subtask into Validation, create or update the required GitHub PR and store its URL/number in ClickUp `agent_metadata`. Subtasks PR from their subtask branch into the parent task branch. Parent tasks PR from the task branch into `dev`. A task in Validation without an open PR is invalid: move it back to `in progress`, open/update the PR, then return it to Validation. Route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks.
+- GitHub review wakeups: keep listening for PR review/comment webhooks. Reply in GitHub to human comments. If a comment asks for or implies a change, reply first with what you will do, move the ClickUp task/subtask to `in progress`, delegate/implement the fix, push the same branch, update the PR, move ClickUp back to `validation`, then reply again in GitHub with what changed. Also add concise ClickUp status comments for model work state; never post Optima runtime/process noise.
+- `merge`: parent-only post-approval automation after the configured final approver/CTO approves the GitHub PR. The GitHub accepted/approved review is the merge trigger. Merge the parent PR into `dev`, verify the Vercel preproduction deployment updates automatically, run a small smoke/regression against preproduction, and only then clean workspaces/worktrees/branches and move ClickUp to `completed`. If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent task, move the parent back to `in progress`, and keep the evidence/PR links in ClickUp.
 - `completed` / `Closed`: no execution unless explicitly reopened.
 
 ## Git, Worktree, PR
@@ -60,7 +61,10 @@ 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 a parent-validation human `Approved` comment triggers merge automation; 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 task -> `dev` through a GitHub PR before entering Validation. Release -> `dev` to `main` only after explicit approval.
+- Required PR gate: every transition into `validation` must have an open GitHub PR. Do not mark Validation with only local commits, evidence, or ClickUp comments.
+- Review/merge cleanup: after the configured final approver/CTO approves and the PR is merged, keep the OpenCode session ids in ClickUp `agent_metadata`; delete only the merged branch/worktree after Vercel preproduction and smoke regression pass. If the task is reopened later, recreate/register the worktree from metadata/branch context and resume the preserved sessions.
+- Final completion gate: parent task completion requires merged PR, Vercel preproduction deployment verified, smoke/regression evidence captured, no open review-change requests, final ClickUp comment with result, and status `completed`.
 - Preserve user work and unrelated dirty files. Stop and ask if unexpected changes appear.
 
 ## Operating Style

package/dist/index.js

@@ -8819,6 +8819,70 @@ function deriveClickUpPrTarget({ isRelease = false, parentTaskId, parentBranch,
   }
   return devBranch;
 }
+function deriveClickUpRequiredPullRequest({ taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", branch = "", parentBranch = "", devBranch = "dev", mainBranch = "main", isRelease = false, githubRemote = "origin", prUrl = "", prNumber = "" } = {}) {
+  const effectiveParent = parentTaskId || taskId;
+  const isSubtask = isClickUpSubtaskRoute({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
+  const sourceBranch = branch || deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
+  const targetBranch = deriveClickUpPrTarget({
+    isRelease,
+    parentBranch: isSubtask ? parentBranch || deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent }) : parentBranch,
+    parentTaskId: isSubtask ? effectiveParent : "",
+    parentTaskType: taskType,
+    taskType,
+    devBranch,
+    mainBranch
+  });
+  return {
+    required: true,
+    sourceBranch,
+    targetBranch,
+    githubRemote,
+    prUrl: String(prUrl || "").trim(),
+    prNumber: String(prNumber || "").trim(),
+    scope: isSubtask ? "subtask_to_parent" : isRelease ? "release_to_main" : "task_to_dev",
+    policy: "validation_requires_open_pull_request"
+  };
+}
+function buildClickUpReviewAutomationPlan({ isSubtask = false, humanApprover = "CTO", preproductionProvider = "Vercel", preproductionEnvironment = "preproduction" } = {}) {
+  return {
+    github_webhooks: {
+      listen_for: ["pull_request_review", "pull_request_review_comment", "issue_comment", "pull_request"],
+      comment_policy: "reply_before_change_and_after_change",
+      change_request_status: "in progress",
+      after_fix_status: "validation",
+      state_storage: "ClickUp agent_metadata.github"
+    },
+    review_comments: [
+      "Answer GitHub comments directly in GitHub.",
+      "If a comment implies a code/doc/test change, first reply with the intended action, move the ClickUp task/subtask to in progress, implement, push the same branch, move it back to validation, update the PR, then reply again with what changed.",
+      "Also update ClickUp with human-readable model work status; runtime/process noise stays in local logs."
+    ],
+    accepted_review: {
+      accepted_by: humanApprover,
+      trigger: "approved_pull_request_review",
+      action: isSubtask ? "merge_subtask_pr_into_parent_branch" : "merge_parent_pr_into_dev",
+      delete_source_branch_after_success: true,
+      delete_worktree_after_success: true,
+      preserve_opencode_sessions_in_agent_metadata: true
+    },
+    preproduction: isSubtask ? {
+      required: false,
+      reason: "Subtask merge stops at parent branch; parent task owns dev/preproduction."
+    } : {
+      required: true,
+      provider: preproductionProvider,
+      environment: preproductionEnvironment,
+      verify_deployment_after_merge: true,
+      run_smoke_regression: true,
+      on_failure: "create_bug_subtasks_and_return_parent_to_in_progress",
+      completion_gate: "preproduction_deployed_and_regression_passed"
+    },
+    completion: {
+      final_clickup_comment_required: true,
+      final_status: isSubtask ? "completed_or_parent_validation" : "completed"
+    }
+  };
+}
 function validateMainWorkspaceBranchSafety({ currentBranch, requiredBranch = "dev", forbiddenBranch = "main" } = {}) {
   const normalized = String(currentBranch ?? "").trim();
   if (!normalized) {
@@ -9481,6 +9545,7 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
   const worktree = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
   const prTarget = isSubtask ? parentBranch : "dev";
   const startFrom = isSubtask ? parentBranch : "dev";
+  const requiredPullRequest = deriveClickUpRequiredPullRequest({ taskId, taskType, parentTaskId: effectiveParent, subtaskId, branch, parentBranch });
   const estimate = preEstimateClickUpWork({ complexity, filesChanged, acceptanceCriteria, unknowns });
   const metadata = mergeClickUpAgentMetadata(existingAgentMetadata, {
     task: {
@@ -9494,6 +9559,10 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       mirror_task_path: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
       delivery_evidence_path: deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent),
+      github: {
+        required_pull_request: requiredPullRequest,
+        review_automation: buildClickUpReviewAutomationPlan({ isSubtask })
+      },
       ...agentMetadata
     }
   });
@@ -9516,6 +9585,10 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       parentBranch: parentBranch || void 0,
       prTarget
     },
+    github: {
+      requiredPullRequest,
+      reviewAutomation: buildClickUpReviewAutomationPlan({ isSubtask })
+    },
     mirror: {
       taskPath: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidenceSummaryPath: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
@@ -9526,14 +9599,15 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       wouldCreate: true
     },
     clickup: {
-      comment: `Starting task from ${startFrom}. Branch: ${branch}. Worktree: ${worktree}. Delivery evidence: ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}.`,
+      comment: `Starting task from ${startFrom}. Branch: ${branch}. Worktree: ${worktree}. Validation PR target: ${requiredPullRequest.targetBranch}. Delivery evidence: ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}.`,
       description,
       fields: {
         Definition: definitionContent,
         "Story Points": estimate.storyPoints,
         agent_metadata: metadata,
         branch,
-        worktree
+        worktree,
+        pr_target: requiredPullRequest.targetBranch
       },
       definition_doc: {
         parent: normalizeClickUpDefinitionDocParent(definitionDocParent),
@@ -9543,23 +9617,29 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     }
   };
 }
-function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], removeAssignees = [], productManagerAssignee = "", requireProductManagerAssignee = true, planDescription = "", definition = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, humansRegistry } = {}) {
+function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], removeAssignees = [], productManagerAssignee = "", requireProductManagerAssignee = true, planDescription = "", definition = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, humansRegistry, taskId = "", taskType = "Tarea", parentTaskId = "", subtaskId = "", branch = "", parentBranch = "", prUrl = "", prNumber = "", githubRemote = "origin", devBranch = "dev", mainBranch = "main", preproductionProvider = "Vercel", preproductionEnvironment = "preproduction" } = {}) {
   const from = normalizeClickUpStatus(fromStatus);
+  const effectiveIsSubtask = Boolean(isSubtask || isClickUpSubtaskRoute({ taskType, parentTaskId: parentTaskId || taskId, subtaskId, taskId }));
   let to = normalizeClickUpStatus(toStatus);
   if (validationFailed) to = "in progress";
-  if (!to && validationPassed) to = isSubtask ? "completed" : "merge";
+  if (!to && validationPassed) to = effectiveIsSubtask ? "completed" : "merge";
   if ((from === "completed" || from === "closed") && !reopen) {
     return { ok: true, noop: true, dryRun: true, message: "Completed/closed task is a no-op unless reopen is explicit." };
   }
   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 && !(rule.parentOnlyFinalApproval && isSubtask);
+  const assignsFinalApprovers = rule.assignFinalApprovers === true && !(rule.parentOnlyFinalApproval && effectiveIsSubtask);
   const requiresPlanCompletionContract = from === "plan" && to === "in progress";
+  const requiresValidationPullRequest = from === "in progress" && to === "validation";
   const definitionContent = compactMarkdownValue(definition);
   const description = compactMarkdownValue(planDescription);
+  const canDerivePullRequest = Boolean(taskId || branch);
+  const shouldAttachPullRequest = requiresValidationPullRequest || (from === "validation" || to === "merge" || from === "merge") && canDerivePullRequest;
+  const requiredPullRequest = shouldAttachPullRequest && canDerivePullRequest ? deriveClickUpRequiredPullRequest({ taskId, taskType, parentTaskId, subtaskId, branch, parentBranch, devBranch, mainBranch, githubRemote, prUrl, prNumber }) : null;
+  const reviewAutomation = requiredPullRequest ? buildClickUpReviewAutomationPlan({ isSubtask: effectiveIsSubtask, preproductionProvider, preproductionEnvironment }) : null;
   const validationErrors = [];
-  if (rule.parentOnlyFinalApproval && isSubtask) {
+  if (rule.parentOnlyFinalApproval && effectiveIsSubtask) {
     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) {
@@ -9569,19 +9649,34 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     if (!description) validationErrors.push("planDescription is required for the plan-completion ClickUp task description rewrite.");
     if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
   }
+  if (requiresValidationPullRequest) {
+    if (!requiredPullRequest) validationErrors.push("taskId or branch is required before moving a ClickUp task to validation.");
+    if (!requiredPullRequest?.sourceBranch) validationErrors.push("branch/sourceBranch is required before moving a ClickUp task to validation.");
+    if (!requiredPullRequest?.targetBranch) validationErrors.push("PR target branch is required before moving a ClickUp task to validation.");
+    if (!requiredPullRequest?.prUrl && !requiredPullRequest?.prNumber) validationErrors.push("An open GitHub pull request URL or number is required before moving a ClickUp task to validation.");
+  }
   if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
   const finalApprovers = assignsFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
   const explicitRemovals = (removeAssignees || []).filter(Boolean);
   const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
   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 authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask: effectiveIsSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
   const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
+  if (requiredPullRequest) {
+    fields.github_pull_request = JSON.stringify(requiredPullRequest);
+    fields.github_review_automation = JSON.stringify(reviewAutomation);
+  }
   if (definitionContent) fields.Definition = definitionContent;
   return {
     ok: true,
     dryRun: true,
-    transition: { fromStatus: from, toStatus: rule.status, validationPassed, validationFailed, isSubtask },
+    transition: { fromStatus: from, toStatus: rule.status, validationPassed, validationFailed, isSubtask: effectiveIsSubtask },
+    github: requiredPullRequest ? {
+      requiredPullRequest,
+      reviewAutomation
+    } : void 0,
+    vercel: reviewAutomation?.preproduction?.required ? reviewAutomation.preproduction : void 0,
     clickup: {
       status: rule.status,
       assignees: assigned,
@@ -13776,7 +13871,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 export {
   OptimaPlugin as default
 };

package/dist/sanitize_cli.js

@@ -8826,6 +8826,70 @@ function deriveClickUpPrTarget({ isRelease = false, parentTaskId, parentBranch,
   }
   return devBranch;
 }
+function deriveClickUpRequiredPullRequest({ taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", branch = "", parentBranch = "", devBranch = "dev", mainBranch = "main", isRelease = false, githubRemote = "origin", prUrl = "", prNumber = "" } = {}) {
+  const effectiveParent = parentTaskId || taskId;
+  const isSubtask = isClickUpSubtaskRoute({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
+  const sourceBranch = branch || deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
+  const targetBranch = deriveClickUpPrTarget({
+    isRelease,
+    parentBranch: isSubtask ? parentBranch || deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent }) : parentBranch,
+    parentTaskId: isSubtask ? effectiveParent : "",
+    parentTaskType: taskType,
+    taskType,
+    devBranch,
+    mainBranch
+  });
+  return {
+    required: true,
+    sourceBranch,
+    targetBranch,
+    githubRemote,
+    prUrl: String(prUrl || "").trim(),
+    prNumber: String(prNumber || "").trim(),
+    scope: isSubtask ? "subtask_to_parent" : isRelease ? "release_to_main" : "task_to_dev",
+    policy: "validation_requires_open_pull_request"
+  };
+}
+function buildClickUpReviewAutomationPlan({ isSubtask = false, humanApprover = "CTO", preproductionProvider = "Vercel", preproductionEnvironment = "preproduction" } = {}) {
+  return {
+    github_webhooks: {
+      listen_for: ["pull_request_review", "pull_request_review_comment", "issue_comment", "pull_request"],
+      comment_policy: "reply_before_change_and_after_change",
+      change_request_status: "in progress",
+      after_fix_status: "validation",
+      state_storage: "ClickUp agent_metadata.github"
+    },
+    review_comments: [
+      "Answer GitHub comments directly in GitHub.",
+      "If a comment implies a code/doc/test change, first reply with the intended action, move the ClickUp task/subtask to in progress, implement, push the same branch, move it back to validation, update the PR, then reply again with what changed.",
+      "Also update ClickUp with human-readable model work status; runtime/process noise stays in local logs."
+    ],
+    accepted_review: {
+      accepted_by: humanApprover,
+      trigger: "approved_pull_request_review",
+      action: isSubtask ? "merge_subtask_pr_into_parent_branch" : "merge_parent_pr_into_dev",
+      delete_source_branch_after_success: true,
+      delete_worktree_after_success: true,
+      preserve_opencode_sessions_in_agent_metadata: true
+    },
+    preproduction: isSubtask ? {
+      required: false,
+      reason: "Subtask merge stops at parent branch; parent task owns dev/preproduction."
+    } : {
+      required: true,
+      provider: preproductionProvider,
+      environment: preproductionEnvironment,
+      verify_deployment_after_merge: true,
+      run_smoke_regression: true,
+      on_failure: "create_bug_subtasks_and_return_parent_to_in_progress",
+      completion_gate: "preproduction_deployed_and_regression_passed"
+    },
+    completion: {
+      final_clickup_comment_required: true,
+      final_status: isSubtask ? "completed_or_parent_validation" : "completed"
+    }
+  };
+}
 function validateMainWorkspaceBranchSafety({ currentBranch, requiredBranch = "dev", forbiddenBranch = "main" } = {}) {
   const normalized = String(currentBranch ?? "").trim();
   if (!normalized) {
@@ -9488,6 +9552,7 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
   const worktree = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
   const prTarget = isSubtask ? parentBranch : "dev";
   const startFrom = isSubtask ? parentBranch : "dev";
+  const requiredPullRequest = deriveClickUpRequiredPullRequest({ taskId, taskType, parentTaskId: effectiveParent, subtaskId, branch, parentBranch });
   const estimate = preEstimateClickUpWork({ complexity, filesChanged, acceptanceCriteria, unknowns });
   const metadata = mergeClickUpAgentMetadata(existingAgentMetadata, {
     task: {
@@ -9501,6 +9566,10 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       mirror_task_path: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
       delivery_evidence_path: deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent),
+      github: {
+        required_pull_request: requiredPullRequest,
+        review_automation: buildClickUpReviewAutomationPlan({ isSubtask })
+      },
       ...agentMetadata
     }
   });
@@ -9523,6 +9592,10 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       parentBranch: parentBranch || void 0,
       prTarget
     },
+    github: {
+      requiredPullRequest,
+      reviewAutomation: buildClickUpReviewAutomationPlan({ isSubtask })
+    },
     mirror: {
       taskPath: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidenceSummaryPath: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
@@ -9533,14 +9606,15 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       wouldCreate: true
     },
     clickup: {
-      comment: `Starting task from ${startFrom}. Branch: ${branch}. Worktree: ${worktree}. Delivery evidence: ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}.`,
+      comment: `Starting task from ${startFrom}. Branch: ${branch}. Worktree: ${worktree}. Validation PR target: ${requiredPullRequest.targetBranch}. Delivery evidence: ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}.`,
       description,
       fields: {
         Definition: definitionContent,
         "Story Points": estimate.storyPoints,
         agent_metadata: metadata,
         branch,
-        worktree
+        worktree,
+        pr_target: requiredPullRequest.targetBranch
       },
       definition_doc: {
         parent: normalizeClickUpDefinitionDocParent(definitionDocParent),
@@ -9550,23 +9624,29 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     }
   };
 }
-function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], removeAssignees = [], productManagerAssignee = "", requireProductManagerAssignee = true, planDescription = "", definition = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, humansRegistry } = {}) {
+function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], removeAssignees = [], productManagerAssignee = "", requireProductManagerAssignee = true, planDescription = "", definition = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, humansRegistry, taskId = "", taskType = "Tarea", parentTaskId = "", subtaskId = "", branch = "", parentBranch = "", prUrl = "", prNumber = "", githubRemote = "origin", devBranch = "dev", mainBranch = "main", preproductionProvider = "Vercel", preproductionEnvironment = "preproduction" } = {}) {
   const from = normalizeClickUpStatus(fromStatus);
+  const effectiveIsSubtask = Boolean(isSubtask || isClickUpSubtaskRoute({ taskType, parentTaskId: parentTaskId || taskId, subtaskId, taskId }));
   let to = normalizeClickUpStatus(toStatus);
   if (validationFailed) to = "in progress";
-  if (!to && validationPassed) to = isSubtask ? "completed" : "merge";
+  if (!to && validationPassed) to = effectiveIsSubtask ? "completed" : "merge";
   if ((from === "completed" || from === "closed") && !reopen) {
     return { ok: true, noop: true, dryRun: true, message: "Completed/closed task is a no-op unless reopen is explicit." };
   }
   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 && !(rule.parentOnlyFinalApproval && isSubtask);
+  const assignsFinalApprovers = rule.assignFinalApprovers === true && !(rule.parentOnlyFinalApproval && effectiveIsSubtask);
   const requiresPlanCompletionContract = from === "plan" && to === "in progress";
+  const requiresValidationPullRequest = from === "in progress" && to === "validation";
   const definitionContent = compactMarkdownValue(definition);
   const description = compactMarkdownValue(planDescription);
+  const canDerivePullRequest = Boolean(taskId || branch);
+  const shouldAttachPullRequest = requiresValidationPullRequest || (from === "validation" || to === "merge" || from === "merge") && canDerivePullRequest;
+  const requiredPullRequest = shouldAttachPullRequest && canDerivePullRequest ? deriveClickUpRequiredPullRequest({ taskId, taskType, parentTaskId, subtaskId, branch, parentBranch, devBranch, mainBranch, githubRemote, prUrl, prNumber }) : null;
+  const reviewAutomation = requiredPullRequest ? buildClickUpReviewAutomationPlan({ isSubtask: effectiveIsSubtask, preproductionProvider, preproductionEnvironment }) : null;
   const validationErrors = [];
-  if (rule.parentOnlyFinalApproval && isSubtask) {
+  if (rule.parentOnlyFinalApproval && effectiveIsSubtask) {
     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) {
@@ -9576,19 +9656,34 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     if (!description) validationErrors.push("planDescription is required for the plan-completion ClickUp task description rewrite.");
     if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
   }
+  if (requiresValidationPullRequest) {
+    if (!requiredPullRequest) validationErrors.push("taskId or branch is required before moving a ClickUp task to validation.");
+    if (!requiredPullRequest?.sourceBranch) validationErrors.push("branch/sourceBranch is required before moving a ClickUp task to validation.");
+    if (!requiredPullRequest?.targetBranch) validationErrors.push("PR target branch is required before moving a ClickUp task to validation.");
+    if (!requiredPullRequest?.prUrl && !requiredPullRequest?.prNumber) validationErrors.push("An open GitHub pull request URL or number is required before moving a ClickUp task to validation.");
+  }
   if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
   const finalApprovers = assignsFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
   const explicitRemovals = (removeAssignees || []).filter(Boolean);
   const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
   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 authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask: effectiveIsSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
   const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
+  if (requiredPullRequest) {
+    fields.github_pull_request = JSON.stringify(requiredPullRequest);
+    fields.github_review_automation = JSON.stringify(reviewAutomation);
+  }
   if (definitionContent) fields.Definition = definitionContent;
   return {
     ok: true,
     dryRun: true,
-    transition: { fromStatus: from, toStatus: rule.status, validationPassed, validationFailed, isSubtask },
+    transition: { fromStatus: from, toStatus: rule.status, validationPassed, validationFailed, isSubtask: effectiveIsSubtask },
+    github: requiredPullRequest ? {
+      requiredPullRequest,
+      reviewAutomation
+    } : void 0,
+    vercel: reviewAutomation?.preproduction?.required ? reviewAutomation.preproduction : void 0,
     clickup: {
       status: rule.status,
       assignees: assigned,
@@ -13783,7 +13878,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpReviewAutomationPlan, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, compactPromptPath, createClickUpApiClient, createTestClickUpApiClient, createOpenCodeSession, createOpenCodeSessionControl, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpTaskWorktreeForWebhook, ensureClickUpTaskWorktreeOpenChamber, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, inspectOpenCodeSessionActivity, isClickUpDerivedWorktreeSibling, isClickUpSubtaskRoute, isClickUpWebhookStateActive, isSameOrNestedPath, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, openCodeSessionExists, promptOpenCodeSessionControl, probeOpenCodeSessionControl, readClickUpCommentLedger, readClickUpWebhookState, readOpenCodeSessionControl, readOpenCodeSessionMessages, reconcileClickUpStartup, registerOpenChamberClickUpWorktree, scheduleClickUpAssignmentWatchdog, scheduleClickUpStartupReconciliation, syncOpenChamberWorktreeVisibility, waitForOpenCodeReadiness, recordClickUpCommentVersionProcessed, resyncClickUpWebhookForSignatureDrift, resolveIncludeFile, resolveIncludes, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, summarizeOpenCodeMessages, verifyOpenCodeSessionEventDelivery, stableClickUpCommentVersionMarker, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpRequiredPullRequest, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatRepairResult, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, optimaRepairDependencies, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, planOptimaRepair, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 
 // src/sanitize_cli.js
 var { migrateLegacyOptimaLayout: migrateLegacyOptimaLayout2 } = OptimaPlugin.__internals;

package/docs/guides/AGENTS.md

@@ -61,3 +61,14 @@ Use shared policies and additive agent files by default. Do not create or popula
 - PMA links the task to an approved SCR.
 - Architect helps decompose the work into slice-based subtasks.
 - `workflow_runner` executes the end-to-end delivery cycle through specialist delegation while PMA waits for completion notification.
+
+## ClickUp-First PR And Preproduction Gate
+
+For ClickUp-first delivery, Validation is a GitHub PR state, not a comment-only handoff.
+
+- Subtasks open/update a PR from the subtask branch into the parent task branch before entering Validation.
+- Parent tasks open/update a PR from the task branch into `dev` before entering Validation.
+- GitHub review/comment webhooks wake the workflow owner. The agent replies in GitHub; if a comment requires a change, it moves ClickUp back to `in progress`, fixes/pushes the same branch, returns ClickUp to `validation`, updates the PR, and replies again with the result.
+- The configured final approver/CTO approving the parent PR is the merge trigger. After merge to `dev`, Vercel preproduction must deploy automatically and pass a small smoke/regression check before cleanup and ClickUp `completed`.
+- If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent and return the parent to `in progress`.
+- Worktrees/branches may be deleted only after the merge and preproduction gate pass. OpenCode session ids remain in ClickUp `agent_metadata` so a reopened task can recreate the worktree and resume context.

package/package.json

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

package/templates/optima.yaml.template

@@ -67,5 +67,24 @@ workflow:
       subtask: parent_branch
       parent: dev
       release: main
+    validation_requires_pull_request: true # A task/subtask cannot enter Validation without an open GitHub PR
+    review_webhooks:
+      enabled: true
+      events:
+        - pull_request_review
+        - pull_request_review_comment
+        - issue_comment
+        - pull_request
+      comment_policy: reply_before_change_and_after_change
+      change_request_status: in progress
+      after_fix_status: validation
+      accepted_by: CTO
+  vercel:
+    preproduction:
+      required_for_parent_tasks: true
+      environment: preproduction
+      verify_deployment_after_merge: true
+      smoke_regression_required: true
+      on_failure: create_bug_subtasks_and_return_parent_to_in_progress
 
 agents: