@defend-tech/opencode-optima 0.1.75 → 0.1.76

package/assets/agents/tech_lead.md

@@ -7,6 +7,7 @@ tools:
   optima_stop_discussion: true
   optima_github_auth_mode: true
   optima_github_commit_worktree: true
+  optima_github_verify_vercel_pr: true
 ---
 You are the Tech Lead Agent: own technical quality, behavioral verification, technical guidance, and direct-path commit authority.
 
@@ -23,6 +24,7 @@ You are the Tech Lead Agent: own technical quality, behavioral verification, tec
 - Review feasibility, scope, architecture fit, risk, and task complexity before implementation proceeds.
 - In mini/direct paths, implement when assigned; in full mode, guide specialists instead of absorbing all work by default.
 - For ClickUp/GitHub delivery, do not create local `git commit` commits. Use `optima_github_commit_worktree` so commits are created by the Optima GitHub App/bot and verify that the returned commit verification is `verified: true` before requesting approval or closure.
+- For parent PR validation, call `optima_github_verify_vercel_pr` before approving technical handoff. A failing Vercel status, missing deployment, or non-functional deployment URL is implementation work to fix, not a CTO/PO handoff.
 - Verify behavior against user stories and ACs through code inspection, builds, tests, and `optima_validate` where relevant.
 - Review code quality, maintainability, architecture adherence, performance, security, and test coverage.
 - Confirm technical/feature documentation closure before any final commit.

package/assets/agents/workflow_product_manager.md

@@ -12,6 +12,7 @@ tools:
   optima_github_comment_pr: true
   optima_github_reply_review_comment: true
   optima_github_review_pr: true
+  optima_github_verify_vercel_pr: true
   optima_github_merge_pr: true
   optima_github_commit_worktree: true
 ---
@@ -49,11 +50,11 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 ## Status Actions
 
 - Human registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in the task worktree, use the Optima-provided Human Role Fallback Registry and configured ClickUp IDs instead of blocking solely on the missing repo-local file.
-- Human approval allowlist: never assign `CTO`/`PO` except for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign them for generic handoff, routine validation, cleanup, subtasks, or partial-phase stops.
+- Human approval allowlist: never assign `CTO`/`PO` except for parent `plan` questions with clear ClickUp comments, real `in progress` blockers from missing credentials/permissions/tools/access, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. Do not assign them for generic handoff, routine validation, cleanup, subtasks, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - `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`: before moving any task/subtask into Validation, create or update the required GitHub PR through `optima_github_create_pr`, store its URL/number in ClickUp `agent_metadata`, and leave a concise model-owned ClickUp status comment with the PR link, source branch, target branch, and current validation owner. Subtasks PR from their subtask branch into the parent task branch. Parent tasks PR from the task branch into `dev`. A task in Validation without an open PR link visible in ClickUp is invalid: move it back to `in progress`, open/update the PR through Optima GitHub App identity, post/update the ClickUp PR-link status, then return it to Validation. Route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks.
+- `validation`: before moving any task/subtask into Validation, create or update the required GitHub PR through `optima_github_create_pr`, store its URL/number in ClickUp `agent_metadata`, and leave a concise model-owned ClickUp status comment with the PR link, source branch, target branch, and current validation owner. Subtasks PR from their subtask branch into the parent task branch. Parent tasks PR from the task branch into `dev`. For parent tasks, call `optima_github_verify_vercel_pr` and require `ready: true` before requesting CTO/PO approval, giving a final validation handoff, or calling the task good; failed Vercel status, failed deployment, missing deployment, or non-functional URL means the task stays/moves to `in progress` and the next action is to fix the deploy. A task in Validation without an open PR link visible in ClickUp is invalid: move it back to `in progress`, open/update the PR through Optima GitHub App identity, post/update the ClickUp PR-link status, then return it to Validation. Route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks.
 - GitHub review wakeups: keep listening for PR review/comment webhooks. Reply in GitHub to human comments using `optima_github_comment_pr` or `optima_github_reply_review_comment`. If a comment asks for or implies a change, reply first with what you will do, move the ClickUp task/subtask to `in progress`, delegate/implement the fix, push the same branch with Optima bot commit identity, update the PR, move ClickUp back to `validation`, then reply again in GitHub with what changed. Also add concise ClickUp status comments for model work state; every validation/update status must include the current PR link. Never post Optima runtime/process noise.
 - `merge`: parent-only post-approval automation after the configured final approver/CTO approves the GitHub PR. The GitHub accepted/approved review is the merge trigger. Merge the parent PR into `dev`, verify the Vercel preproduction deployment updates automatically, run a small smoke/regression against preproduction, and only then clean workspaces/worktrees/branches and move ClickUp to `completed`. If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent task, move the parent back to `in progress`, and keep the evidence/PR links in ClickUp.
 - `completed` / `Closed`: no execution unless explicitly reopened.
@@ -70,7 +71,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - 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 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 and a ClickUp-visible model status comment containing that PR link. Do not mark Validation with only local commits, evidence, or comments without the PR URL.
+- Required PR gate: every transition into `validation` must have an open GitHub PR and a ClickUp-visible model status comment containing that PR link. Parent task validation also requires `optima_github_verify_vercel_pr` to return `ready: true` with the Vercel preproduction/preview deployment URL responding successfully before human approval or CTO/PO handoff. Do not mark Validation with only local commits, evidence, comments without the PR URL, or a failing/pending Vercel deploy.
 - Identity gate: PRs/comments/reviews/merges must be authored by the Optima GitHub App/bot identity, not the human operator. Commits must be created through `optima_github_commit_worktree` using the GitHub App API; if the returned commit verification is not `verified: true` or GitHub does not show commits as Verified, do not request human approval or complete the task.
 - 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`.

package/dist/index.js

@@ -10296,10 +10296,88 @@ function treeEntryForWorktreePath(worktree, gitPath) {
     encoding: "base64"
   };
 }
+function appendGitHubQuery(pathname, params = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params || {})) {
+    if (value === void 0 || value === null || value === "") continue;
+    query.set(key, String(value));
+  }
+  const suffix = query.toString();
+  return suffix ? `${pathname}?${suffix}` : pathname;
+}
+function timestampMs(value = "") {
+  const parsed = Date.parse(String(value || ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function sortNewestFirst(items = []) {
+  return [...items].sort((a, b) => {
+    const bTime = Math.max(timestampMs(b?.updated_at), timestampMs(b?.created_at));
+    const aTime = Math.max(timestampMs(a?.updated_at), timestampMs(a?.created_at));
+    return bTime - aTime;
+  });
+}
+function matchesVercelStatusContext(context = "", expected = "") {
+  const actual = String(context || "").trim();
+  const wanted = String(expected || "").trim();
+  if (wanted && actual === wanted) return true;
+  const lower = actual.toLowerCase();
+  if (!lower.includes("vercel")) return false;
+  if (!wanted) return lower.includes("preproduction") || lower.includes("defend-preproduction");
+  const wantedLower = wanted.toLowerCase();
+  return wantedLower.split(/\s+|–|-/).filter((part) => part && part !== "vercel").every((part) => lower.includes(part));
+}
+function selectFunctionalDeploymentUrl(status = {}, deployment = {}) {
+  for (const candidate of [
+    status?.environment_url,
+    deployment?.environment_url,
+    status?.target_url,
+    deployment?.target_url
+  ]) {
+    const value = String(candidate || "").trim();
+    if (!value) continue;
+    try {
+      const url = new URL(value);
+      if (url.protocol === "http:" || url.protocol === "https:") return value;
+    } catch {
+    }
+  }
+  return "";
+}
+async function checkFunctionalDeploymentUrl(url, fetchImpl = globalThis.fetch) {
+  const target = String(url || "").trim();
+  if (!target) return { ok: false, reason: "url_missing" };
+  if (typeof fetchImpl !== "function") return { ok: false, reason: "fetch_unavailable", url: target };
+  const signal = typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(8e3) : void 0;
+  const probe = async (method) => {
+    const response = await fetchImpl(target, { method, redirect: "follow", signal });
+    return {
+      ok: response.status >= 200 && response.status < 400,
+      status: response.status,
+      statusText: response.statusText || "",
+      url: response.url || target,
+      method
+    };
+  };
+  try {
+    const head = await probe("HEAD");
+    if (head.ok) return head;
+    const get = await probe("GET");
+    return get.ok ? get : { ...get, reason: "http_not_ok" };
+  } catch (error) {
+    try {
+      const get = await probe("GET");
+      return get.ok ? get : { ...get, reason: "http_not_ok" };
+    } catch (secondError) {
+      return { ok: false, reason: "request_failed", url: target, error: secondError.message || error.message };
+    }
+  }
+}
 function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
   const staticToken = resolveSecretReference(config?.apiToken);
   const appConfig = isPlainObject(config?.app) ? config.app : {};
-  const appEnabled = appConfig.enabled === true || Boolean(appConfig.appId && appConfig.installationId && (appConfig.privateKey || appConfig.privateKeyFile));
+  const appId = resolveSecretReference(appConfig.appId || appConfig.app_id || "");
+  const installationId = resolveSecretReference(appConfig.installationId || appConfig.installation_id || "");
+  const appEnabled = appConfig.enabled === true || Boolean(appId && installationId && (appConfig.privateKey || appConfig.privateKeyFile));
   const privateKey = resolveGitHubAppPrivateKey(appConfig);
   const owner = String(config?.owner || "").trim();
   const repo = String(config?.repo || "").trim();
@@ -10324,8 +10402,8 @@ function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
     if (!appEnabled) return staticToken || "";
     const nowMs = Date.now();
     if (installationToken && installationTokenExpiresAt - 6e4 > nowMs) return installationToken;
-    const jwt = createGitHubAppJwt({ appId: appConfig.appId, privateKey });
-    const installation = await requestJson(`https://api.github.com/app/installations/${encodeURIComponent(appConfig.installationId)}/access_tokens`, {
+    const jwt = createGitHubAppJwt({ appId, privateKey });
+    const installation = await requestJson(`https://api.github.com/app/installations/${encodeURIComponent(installationId)}/access_tokens`, {
       method: "POST",
       headers: { Authorization: `Bearer ${jwt}` }
     });
@@ -10383,6 +10461,111 @@ function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
       if (commitMessage) body.commit_message = String(commitMessage);
       return request(`/pulls/${encodeURIComponent(pullNumber)}/merge`, { method: "PUT", body });
     },
+    async getCombinedStatus(ref) {
+      return request(`/commits/${encodeURIComponent(String(ref || ""))}/status`);
+    },
+    async listDeployments({ sha = "", ref = "", environment = "", perPage = 30 } = {}) {
+      return request(appendGitHubQuery("/deployments", {
+        sha,
+        ref,
+        environment,
+        per_page: perPage
+      }));
+    },
+    async listDeploymentStatuses(deploymentId) {
+      return request(`/deployments/${encodeURIComponent(deploymentId)}/statuses`);
+    },
+    async verifyVercelPullRequestDeployment({
+      pullNumber,
+      context = "Vercel \u2013 defend-preproduction",
+      environment = "Preview \u2013 defend-preproduction",
+      requireFunctionalUrl = true
+    } = {}) {
+      const pr = await this.getPullRequest(pullNumber);
+      const headSha = String(pr?.head?.sha || "").trim();
+      if (!headSha) return { ok: true, ready: false, reason: "pr_head_sha_missing", pull_request: { number: pullNumber } };
+      const combined = await this.getCombinedStatus(headSha);
+      const statuses = Array.isArray(combined?.statuses) ? combined.statuses : [];
+      const matchingStatuses = statuses.filter((status) => matchesVercelStatusContext(status?.context, context));
+      const selectedStatus = sortNewestFirst(matchingStatuses)[0] || null;
+      if (!selectedStatus) {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_status_missing",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_context: context,
+          combined_state: combined?.state || null
+        };
+      }
+      if (String(selectedStatus.state || "").toLowerCase() !== "success") {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_status_not_success",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_context: context,
+          status: selectedStatus,
+          combined_state: combined?.state || null
+        };
+      }
+      let deployments = await this.listDeployments({ sha: headSha, environment });
+      if (!Array.isArray(deployments) || deployments.length === 0) deployments = await this.listDeployments({ sha: headSha });
+      const selectedDeployment = sortNewestFirst(Array.isArray(deployments) ? deployments : []).find((deployment) => !environment || String(deployment?.environment || "") === environment) || sortNewestFirst(Array.isArray(deployments) ? deployments : [])[0] || null;
+      if (!selectedDeployment?.id) {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_deployment_missing",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_environment: environment,
+          status: selectedStatus
+        };
+      }
+      const deploymentStatuses = await this.listDeploymentStatuses(selectedDeployment.id);
+      const selectedDeploymentStatus = sortNewestFirst(Array.isArray(deploymentStatuses) ? deploymentStatuses : [])[0] || null;
+      if (!selectedDeploymentStatus || String(selectedDeploymentStatus.state || "").toLowerCase() !== "success") {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_deployment_not_success",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_environment: environment,
+          status: selectedStatus,
+          deployment: selectedDeployment,
+          deployment_status: selectedDeploymentStatus
+        };
+      }
+      const url = selectFunctionalDeploymentUrl(selectedDeploymentStatus, selectedDeployment);
+      const urlCheck = requireFunctionalUrl ? await checkFunctionalDeploymentUrl(url, fetchImpl) : { ok: Boolean(url), reason: url ? void 0 : "url_missing", url };
+      if (requireFunctionalUrl && !urlCheck.ok) {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_url_not_functional",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_environment: environment,
+          status: selectedStatus,
+          deployment: selectedDeployment,
+          deployment_status: selectedDeploymentStatus,
+          url,
+          url_check: urlCheck
+        };
+      }
+      return {
+        ok: true,
+        ready: true,
+        reason: "vercel_pr_deployment_ready",
+        pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+        required_context: context,
+        required_environment: environment,
+        status: selectedStatus,
+        deployment: selectedDeployment,
+        deployment_status: selectedDeploymentStatus,
+        url,
+        url_check: urlCheck
+      };
+    },
     async commitWorktree({ worktree, branch = "", message = "", runGitFn = runGit, syncLocal = false } = {}) {
       const directory = path6.resolve(String(worktree || ""));
       if (!directory || !fs5.existsSync(directory)) throw new Error("worktree does not exist");
@@ -10432,7 +10615,7 @@ function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
       };
     },
     async authMode() {
-      if (appEnabled) return { mode: "github_app", appId: String(appConfig.appId || ""), installationId: String(appConfig.installationId || "") };
+      if (appEnabled) return { mode: "github_app", appId, installationId };
       if (staticToken) return { mode: "token" };
       return { mode: "anonymous" };
     }
@@ -14256,6 +14439,31 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         }
       }
     }),
+    optima_github_verify_vercel_pr: tool({
+      description: "Verify that a PR head commit has a successful Vercel preproduction deployment and a functional deployment URL before validation/handoff",
+      args: {
+        pr_number: tool.schema.number().describe("Pull request number"),
+        context: tool.schema.string().describe("Required GitHub status context; defaults to 'Vercel \u2013 defend-preproduction'"),
+        environment: tool.schema.string().describe("Required GitHub deployment environment; defaults to 'Preview \u2013 defend-preproduction'"),
+        require_functional_url: tool.schema.string().describe("Set to 'false' to skip HTTP probing of the deployment URL")
+      },
+      async execute(args) {
+        try {
+          const auth = await requireGitHubAppClient();
+          if (!auth.ok) return JSON.stringify(auth, null, 2);
+          if (!runtimeGitHubClient?.verifyVercelPullRequestDeployment) return JSON.stringify({ ok: false, error: "github_client_unavailable" }, null, 2);
+          const result = await runtimeGitHubClient.verifyVercelPullRequestDeployment({
+            pullNumber: args.pr_number,
+            context: args.context || "Vercel \u2013 defend-preproduction",
+            environment: args.environment || "Preview \u2013 defend-preproduction",
+            requireFunctionalUrl: String(args.require_functional_url || "true").toLowerCase() !== "false"
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
     optima_github_merge_pr: tool({
       description: "Merge a GitHub PR through the Optima GitHub App identity after required human approval gates pass",
       args: {

package/dist/sanitize_cli.js

@@ -10303,10 +10303,88 @@ function treeEntryForWorktreePath(worktree, gitPath) {
     encoding: "base64"
   };
 }
+function appendGitHubQuery(pathname, params = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params || {})) {
+    if (value === void 0 || value === null || value === "") continue;
+    query.set(key, String(value));
+  }
+  const suffix = query.toString();
+  return suffix ? `${pathname}?${suffix}` : pathname;
+}
+function timestampMs(value = "") {
+  const parsed = Date.parse(String(value || ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function sortNewestFirst(items = []) {
+  return [...items].sort((a, b) => {
+    const bTime = Math.max(timestampMs(b?.updated_at), timestampMs(b?.created_at));
+    const aTime = Math.max(timestampMs(a?.updated_at), timestampMs(a?.created_at));
+    return bTime - aTime;
+  });
+}
+function matchesVercelStatusContext(context = "", expected = "") {
+  const actual = String(context || "").trim();
+  const wanted = String(expected || "").trim();
+  if (wanted && actual === wanted) return true;
+  const lower = actual.toLowerCase();
+  if (!lower.includes("vercel")) return false;
+  if (!wanted) return lower.includes("preproduction") || lower.includes("defend-preproduction");
+  const wantedLower = wanted.toLowerCase();
+  return wantedLower.split(/\s+|–|-/).filter((part) => part && part !== "vercel").every((part) => lower.includes(part));
+}
+function selectFunctionalDeploymentUrl(status = {}, deployment = {}) {
+  for (const candidate of [
+    status?.environment_url,
+    deployment?.environment_url,
+    status?.target_url,
+    deployment?.target_url
+  ]) {
+    const value = String(candidate || "").trim();
+    if (!value) continue;
+    try {
+      const url = new URL(value);
+      if (url.protocol === "http:" || url.protocol === "https:") return value;
+    } catch {
+    }
+  }
+  return "";
+}
+async function checkFunctionalDeploymentUrl(url, fetchImpl = globalThis.fetch) {
+  const target = String(url || "").trim();
+  if (!target) return { ok: false, reason: "url_missing" };
+  if (typeof fetchImpl !== "function") return { ok: false, reason: "fetch_unavailable", url: target };
+  const signal = typeof AbortSignal !== "undefined" && typeof AbortSignal.timeout === "function" ? AbortSignal.timeout(8e3) : void 0;
+  const probe = async (method) => {
+    const response = await fetchImpl(target, { method, redirect: "follow", signal });
+    return {
+      ok: response.status >= 200 && response.status < 400,
+      status: response.status,
+      statusText: response.statusText || "",
+      url: response.url || target,
+      method
+    };
+  };
+  try {
+    const head = await probe("HEAD");
+    if (head.ok) return head;
+    const get = await probe("GET");
+    return get.ok ? get : { ...get, reason: "http_not_ok" };
+  } catch (error) {
+    try {
+      const get = await probe("GET");
+      return get.ok ? get : { ...get, reason: "http_not_ok" };
+    } catch (secondError) {
+      return { ok: false, reason: "request_failed", url: target, error: secondError.message || error.message };
+    }
+  }
+}
 function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
   const staticToken = resolveSecretReference(config?.apiToken);
   const appConfig = isPlainObject(config?.app) ? config.app : {};
-  const appEnabled = appConfig.enabled === true || Boolean(appConfig.appId && appConfig.installationId && (appConfig.privateKey || appConfig.privateKeyFile));
+  const appId = resolveSecretReference(appConfig.appId || appConfig.app_id || "");
+  const installationId = resolveSecretReference(appConfig.installationId || appConfig.installation_id || "");
+  const appEnabled = appConfig.enabled === true || Boolean(appId && installationId && (appConfig.privateKey || appConfig.privateKeyFile));
   const privateKey = resolveGitHubAppPrivateKey(appConfig);
   const owner = String(config?.owner || "").trim();
   const repo = String(config?.repo || "").trim();
@@ -10331,8 +10409,8 @@ function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
     if (!appEnabled) return staticToken || "";
     const nowMs = Date.now();
     if (installationToken && installationTokenExpiresAt - 6e4 > nowMs) return installationToken;
-    const jwt = createGitHubAppJwt({ appId: appConfig.appId, privateKey });
-    const installation = await requestJson(`https://api.github.com/app/installations/${encodeURIComponent(appConfig.installationId)}/access_tokens`, {
+    const jwt = createGitHubAppJwt({ appId, privateKey });
+    const installation = await requestJson(`https://api.github.com/app/installations/${encodeURIComponent(installationId)}/access_tokens`, {
       method: "POST",
       headers: { Authorization: `Bearer ${jwt}` }
     });
@@ -10390,6 +10468,111 @@ function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
       if (commitMessage) body.commit_message = String(commitMessage);
       return request(`/pulls/${encodeURIComponent(pullNumber)}/merge`, { method: "PUT", body });
     },
+    async getCombinedStatus(ref) {
+      return request(`/commits/${encodeURIComponent(String(ref || ""))}/status`);
+    },
+    async listDeployments({ sha = "", ref = "", environment = "", perPage = 30 } = {}) {
+      return request(appendGitHubQuery("/deployments", {
+        sha,
+        ref,
+        environment,
+        per_page: perPage
+      }));
+    },
+    async listDeploymentStatuses(deploymentId) {
+      return request(`/deployments/${encodeURIComponent(deploymentId)}/statuses`);
+    },
+    async verifyVercelPullRequestDeployment({
+      pullNumber,
+      context = "Vercel \u2013 defend-preproduction",
+      environment = "Preview \u2013 defend-preproduction",
+      requireFunctionalUrl = true
+    } = {}) {
+      const pr = await this.getPullRequest(pullNumber);
+      const headSha = String(pr?.head?.sha || "").trim();
+      if (!headSha) return { ok: true, ready: false, reason: "pr_head_sha_missing", pull_request: { number: pullNumber } };
+      const combined = await this.getCombinedStatus(headSha);
+      const statuses = Array.isArray(combined?.statuses) ? combined.statuses : [];
+      const matchingStatuses = statuses.filter((status) => matchesVercelStatusContext(status?.context, context));
+      const selectedStatus = sortNewestFirst(matchingStatuses)[0] || null;
+      if (!selectedStatus) {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_status_missing",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_context: context,
+          combined_state: combined?.state || null
+        };
+      }
+      if (String(selectedStatus.state || "").toLowerCase() !== "success") {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_status_not_success",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_context: context,
+          status: selectedStatus,
+          combined_state: combined?.state || null
+        };
+      }
+      let deployments = await this.listDeployments({ sha: headSha, environment });
+      if (!Array.isArray(deployments) || deployments.length === 0) deployments = await this.listDeployments({ sha: headSha });
+      const selectedDeployment = sortNewestFirst(Array.isArray(deployments) ? deployments : []).find((deployment) => !environment || String(deployment?.environment || "") === environment) || sortNewestFirst(Array.isArray(deployments) ? deployments : [])[0] || null;
+      if (!selectedDeployment?.id) {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_deployment_missing",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_environment: environment,
+          status: selectedStatus
+        };
+      }
+      const deploymentStatuses = await this.listDeploymentStatuses(selectedDeployment.id);
+      const selectedDeploymentStatus = sortNewestFirst(Array.isArray(deploymentStatuses) ? deploymentStatuses : [])[0] || null;
+      if (!selectedDeploymentStatus || String(selectedDeploymentStatus.state || "").toLowerCase() !== "success") {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_deployment_not_success",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_environment: environment,
+          status: selectedStatus,
+          deployment: selectedDeployment,
+          deployment_status: selectedDeploymentStatus
+        };
+      }
+      const url = selectFunctionalDeploymentUrl(selectedDeploymentStatus, selectedDeployment);
+      const urlCheck = requireFunctionalUrl ? await checkFunctionalDeploymentUrl(url, fetchImpl) : { ok: Boolean(url), reason: url ? void 0 : "url_missing", url };
+      if (requireFunctionalUrl && !urlCheck.ok) {
+        return {
+          ok: true,
+          ready: false,
+          reason: "vercel_url_not_functional",
+          pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+          required_environment: environment,
+          status: selectedStatus,
+          deployment: selectedDeployment,
+          deployment_status: selectedDeploymentStatus,
+          url,
+          url_check: urlCheck
+        };
+      }
+      return {
+        ok: true,
+        ready: true,
+        reason: "vercel_pr_deployment_ready",
+        pull_request: { number: pr.number, url: pr.html_url, head_sha: headSha },
+        required_context: context,
+        required_environment: environment,
+        status: selectedStatus,
+        deployment: selectedDeployment,
+        deployment_status: selectedDeploymentStatus,
+        url,
+        url_check: urlCheck
+      };
+    },
     async commitWorktree({ worktree, branch = "", message = "", runGitFn = runGit, syncLocal = false } = {}) {
       const directory = path6.resolve(String(worktree || ""));
       if (!directory || !fs5.existsSync(directory)) throw new Error("worktree does not exist");
@@ -10439,7 +10622,7 @@ function createGitHubApiClient(config = {}, fetchImpl = globalThis.fetch) {
       };
     },
     async authMode() {
-      if (appEnabled) return { mode: "github_app", appId: String(appConfig.appId || ""), installationId: String(appConfig.installationId || "") };
+      if (appEnabled) return { mode: "github_app", appId, installationId };
       if (staticToken) return { mode: "token" };
       return { mode: "anonymous" };
     }
@@ -14263,6 +14446,31 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         }
       }
     }),
+    optima_github_verify_vercel_pr: tool({
+      description: "Verify that a PR head commit has a successful Vercel preproduction deployment and a functional deployment URL before validation/handoff",
+      args: {
+        pr_number: tool.schema.number().describe("Pull request number"),
+        context: tool.schema.string().describe("Required GitHub status context; defaults to 'Vercel \u2013 defend-preproduction'"),
+        environment: tool.schema.string().describe("Required GitHub deployment environment; defaults to 'Preview \u2013 defend-preproduction'"),
+        require_functional_url: tool.schema.string().describe("Set to 'false' to skip HTTP probing of the deployment URL")
+      },
+      async execute(args) {
+        try {
+          const auth = await requireGitHubAppClient();
+          if (!auth.ok) return JSON.stringify(auth, null, 2);
+          if (!runtimeGitHubClient?.verifyVercelPullRequestDeployment) return JSON.stringify({ ok: false, error: "github_client_unavailable" }, null, 2);
+          const result = await runtimeGitHubClient.verifyVercelPullRequestDeployment({
+            pullNumber: args.pr_number,
+            context: args.context || "Vercel \u2013 defend-preproduction",
+            environment: args.environment || "Preview \u2013 defend-preproduction",
+            requireFunctionalUrl: String(args.require_functional_url || "true").toLowerCase() !== "false"
+          });
+          return JSON.stringify(result, null, 2);
+        } catch (error) {
+          return JSON.stringify({ ok: false, error: error.message }, null, 2);
+        }
+      }
+    }),
     optima_github_merge_pr: tool({
       description: "Merge a GitHub PR through the Optima GitHub App identity after required human approval gates pass",
       args: {

package/docs/core/agent_orchestration.md

@@ -23,9 +23,9 @@
 - 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, 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.
+- 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` after `optima_github_verify_vercel_pr` returns `ready: true` for the current PR with a functional Vercel preproduction/preview URL. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask planning/validation, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - Store ClickUp `agent_metadata` JSON with session IDs per agent/type/task/subtask; keep `Definition` as the plan contract and final Documentation as delivered behavior docs.
-- Validation is not complete until the model leaves the current GitHub PR link visible in ClickUp with source branch, target branch, and validation owner; Optima runtime must still limit its own ClickUp writes to metadata.
+- Validation is not complete until the model leaves the current GitHub PR link visible in ClickUp with source branch, target branch, validation owner, and the `optima_github_verify_vercel_pr` result for parent PRs; Optima runtime must still limit its own ClickUp writes to metadata.
 - PR creation, PR comments, reviews, merges, and commits must use the Optima GitHub App/API identity, not a human token. Final commits for ClickUp/GitHub delivery are created with `optima_github_commit_worktree`; human approval must not be requested until GitHub reports those commits as Verified.
 - `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 ClickUp requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, and stores new `ses_...` ids in ClickUp `agent_metadata`. Runtime/process failures stay in local logs and must not create ClickUp comments or tags.
@@ -40,7 +40,7 @@
 - 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` 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.
+- After parent Tech Lead and Validator/QA validation passes, the parent task may assign `CTO`/`PO` only when `optima_github_verify_vercel_pr` reports the PR deployment ready with a functional URL; 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/preproduction 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,11 +14,11 @@
 - `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`, 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.
+- 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` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel 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/preproduction receives the code; `completed`/`Closed` ignore unless reopened.
 - Shared-worktree rule: one active `implementation` task at a time; isolated `investigation`/`spec` may run in parallel if non-conflicting.
 - Git rules: principal workspace stays on `dev`, never `main`; parent branches use `<type>/<parent-id>`; subtask branches use non-nested `<type>/<parent-id>-subtask-<subtask-id>` and pending subtasks use `<type>/<parent-id>-pending-<title-slug>`; parent task pulls remote once at start; subtasks start from and PR to the parent local branch, bootstrapping the parent from `dev`/`origin/dev` first when missing; PoC branches stay `poc/<clickup-task-id>`; parents PR to `dev`, releases PR `dev` -> `main`; failed/conflicted subtask or parent merges return the affected item to `in progress` for the coding owner; no direct `main` pushes.
 - Store `agent_metadata` session JSON; `Definition` is the plan contract, final Documentation is delivered behavior docs.
-- Validation requires a model-owned ClickUp status comment with the current GitHub PR link, source branch, target branch, and validation owner; Optima runtime itself writes only metadata/logs.
+- Validation requires a model-owned ClickUp status comment with the current GitHub PR link, source branch, target branch, validation owner, and parent PR Vercel gate result from `optima_github_verify_vercel_pr`; Optima runtime itself writes only metadata/logs.
 - PRs, GitHub comments/reviews/merges, and final commits use Optima GitHub App/API identity; create final commits with `optima_github_commit_worktree` and require GitHub `Verified` before human approval.
 - `workflow_product_manager` is registered only when opt-in ClickUp webhook mode is complete and active/valid.
 - Webhook mode validates ClickUp `X-Signature` HMAC SHA-256, routes only PM-assigned non-terminal status/assignee events, routes comments only on `@Defend Tech Product Manager`, writes new `ses_...` ids to `agent_metadata`, and keeps runtime/process failures in local logs, never ClickUp comments/tags.

package/docs/core/role_contracts.md

@@ -21,9 +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.
-- 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.
+- 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` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel preproduction/preview URL. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask work, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - Subtask merge authority belongs to Validator/QA after successful subtask validation: subtask PRs target and merge into the parent branch/workspace without `CTO`/`PO` assignment or approval.
-- Parent merge authority is split: after Tech Lead and Validator/QA pass, 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.
+- Parent merge authority is split: after Tech Lead and Validator/QA pass plus a ready Vercel PR deployment gate, WPM/Validator may assign `CTO`/`PO` only under the parent-validation allowlist; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges to `dev`, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev/preproduction environment contains the code.
 - 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,9 +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.
-- 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.
+- 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` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL; never use it for generic handoff, cleanup, subtasks, phase stops, failed Vercel checks, or missing preview URLs.
 - Validator/QA may merge validated subtask PRs into the parent branch/workspace without `CTO`/`PO` assignment or approval.
-- Parent merge authority uses the validation allowlist only: after a 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.
+- Parent merge authority uses the validation allowlist only after a ready Vercel PR deployment gate: after a human comments `Approved`, automation removes human assignees, assigns merge owner/self, merges to `dev`, cleans workspaces/worktrees/branches, pushes, and ensures dev/preproduction receives the code.
 - Failed or conflicted subtask/parent merges return the affected ClickUp item to `in progress` for the coding owner.
 - ClickUp-first Git rules: principal workspace on `dev`, no direct `main` push, parent pulls remote once at start, subtask PRs to parent branch, parent PRs to `dev`, PoC branches stay `poc/<clickup-task-id>`, release PRs `dev` -> `main` only after approval.
 - BA owns product truth and product-facing feature/domain docs.

package/docs/core/task_model.md

@@ -20,7 +20,7 @@
 - Agents must not assign ClickUp tasks to `CTO` or `PO` except for the explicit cases below; generic handoff, routine validation, duplicate-assignee cleanup, or incomplete phase handoff are prohibited.
 - **Parent planning questions:** only a parent task in `plan` may assign `CTO`/`PO`, and only after clear, concrete questions have been posted in ClickUp comments. Subtasks are planned and executed end-to-end without CTO/PO planning assignment.
 - **Real in-progress blocker:** a task in `in progress` may assign/escalate to `CTO`/`PO` only when blocked by missing credentials, permissions, external tools, or access. Agents must not stop at informal phase boundaries such as "I reached phase 1"; phases should have been subtasks, otherwise finish the accepted task.
-- **Parent validation approval:** only a parent task in `validation` may assign `CTO`/`PO` for final validation, and only with a functional preview URL such as `https://<taskid>-preview.defend.tech` or an equivalent working validation URL. After a human comments `Approved`, automation reassigns to itself or the merge owner, removes human assignees, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code.
+- **Parent validation approval:** only a parent task in `validation` may assign `CTO`/`PO` for final validation, and only after `optima_github_verify_vercel_pr` returns `ready: true` for the current parent PR with a functional Vercel preproduction/preview URL. After a human comments `Approved`, automation reassigns to itself or the merge owner, removes human assignees, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev/preproduction environment contains the code.
 
 ## Routing Rules
 

package/docs/core/task_model.prompt.md

@@ -7,7 +7,7 @@
 - ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignored types: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted/linked.
 - Product Manager without workflow never develops; it may pre-estimate "a qué huele" small/medium/large plus rough story points and route development into ClickUp tasks.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md` when present; if missing in a task worktree, use Optima fallback role context/configured ClickUp IDs instead of blocking solely on the missing file.
-- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access, or parent `validation` with a functional preview URL. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev receives the code; `completed`/`Closed` ignore unless reopened.
+- ClickUp-first actions: `backlog` ignore, `plan` plan with `Story Points`, `Definition`, and test strategy; assign `CTO`/`PO` only for parent planning questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/tools/access, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. Subtasks execute end-to-end and merge to the parent branch after Validator/QA passes without CTO/PO approval; parent `Approved` comments trigger automation to remove humans, assign merge owner/self, merge to `dev`, clean workspaces/worktrees/branches, push, and ensure dev/preproduction receives the code; `completed`/`Closed` ignore unless reopened.
 - Routing: keep `tiny` to one slice and usually one specialist; keep `standard` bounded; decompose `complex` into slice-based subtasks.
 - `complex + implementation` normally uses `workflow_runner` in full mode.
 - WPM stores `agent_metadata`, re-estimates `Story Points` on material plan changes, and keeps `Definition` plan contract separate from final Documentation.

package/docs/core/testing_strategy.md

@@ -19,7 +19,7 @@ We adhere to a strict test pyramid strategy to ensure 100% reliability.
 - **Regression:** A full regression suite must be run by the Developer before handing over for technical review.
 - **Split Validation:** Tech Lead reviews architecture, code, PR readiness, standards, and repo-skill use; Validator/QA verifies tests, Playwright flows, regression, required coverage, evidence, and final documentation freshness.
 - **Human Role Registry:** Resolve `CTO` and `PO` from `docs/core/humans.md` when present; if a task worktree lacks that file, use Optima fallback role context and configured ClickUp IDs instead of blocking solely on the missing repo-local file. Use role identifiers in workflow text and automation config.
-- **Human Approval Allowlist:** Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/permissions/tools/access, or parent `validation` with a functional preview URL. Never assign them for generic handoff, routine validation, cleanup, subtasks, or partial-phase stops.
+- **Human Approval Allowlist:** Assign `CTO`/`PO` only for parent `plan` questions with clear ClickUp comments, real `in progress` blockers caused by missing credentials/permissions/tools/access, or parent `validation` after `optima_github_verify_vercel_pr` returns `ready: true` with a functional Vercel URL. Never assign them for generic handoff, routine validation, cleanup, subtasks, partial-phase stops, failed Vercel checks, or missing preview URLs.
 - **Merge Execution Gate:** Validator/QA may merge validated subtask PRs into the parent branch/workspace without human approval. Parent PRs to `dev` require Tech Lead and Validator/QA pass plus the parent-validation allowlist; after a human comments `Approved`, automation removes human assignees, assigns itself or the merge owner, merges, cleans workspaces/worktrees/branches, pushes to `dev`, and ensures the dev environment contains the code. Any conflicted or failed merge returns the affected task/subtask to `in progress` for the coding owner.
 - **Documentation Gate:** Validator/QA must fail validation when final documentation is missing or outdated; `Definition` is only the plan contract, not the delivered documentation.
 - **QA Output Contract:** QA handoffs should state the test strategy used, the results observed, the AC coverage achieved, any documentation impact, open risks, and the recommended next step.

package/docs/guides/AGENTS.md

@@ -70,6 +70,7 @@ For ClickUp-first delivery, Validation is a GitHub PR state, not a comment-only
 - Parent tasks open/update a PR from the task branch into `dev` before entering Validation.
 - Final commits must be created with `optima_github_commit_worktree`, not local `git commit`, so GitHub attributes them to the Optima App/bot and can mark them Verified. If GitHub does not show the commits as Verified, do not request human approval.
 - The model must leave the current PR link visible in ClickUp when it moves a task/subtask to Validation, including source/target branch and validation owner. Optima runtime still writes only metadata/logs; the ClickUp comment is model-owned work status.
+- Parent PR validation must call `optima_github_verify_vercel_pr`; failed Vercel status, missing deployment, or non-functional URL keeps/returns the task to `in progress` and must be fixed before CTO/PO approval or handoff.
 - 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`.

package/package.json

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