@defend-tech/opencode-optima 0.1.16 → 0.1.18

package/dist/index.js

@@ -8017,6 +8017,9 @@ var REPO_LOCAL_POLICIES_README = [
 ].join("\n");
 var activeWorkflows = /* @__PURE__ */ new Map();
 var activeClickUpWebhookListeners = /* @__PURE__ */ new Map();
+var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
+var CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS = 8e3;
+var CLICKUP_WEBHOOK_SIGNAL_STATE = Symbol.for("opencode-optima.clickup-webhook.signal-state");
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
 var objectIdentityMap = /* @__PURE__ */ new WeakMap();
 var objectIdentitySequence = 0;
@@ -9017,6 +9020,26 @@ function clickUpWebhookListItems(response = {}) {
   if (Array.isArray(response?.data?.webhooks)) return response.data.webhooks;
   return [];
 }
+function clickUpWebhookLocationCompatible(webhook = {}, config = {}) {
+  const location = config?.webhook?.location || {};
+  for (const key of ["space_id", "folder_id", "list_id"]) {
+    const expected = String(location[key] || "").trim();
+    if (expected && String(webhook[key] || webhook.location?.[key] || "").trim() !== expected) return false;
+  }
+  return true;
+}
+async function findReusableClickUpWebhook(config, clickupClient = null) {
+  if (!clickupClient?.listWebhooks) return null;
+  const listed = await clickupClient.listWebhooks({ teamId: config.teamId });
+  for (const webhook of clickUpWebhookListItems(listed)) {
+    const remote = normalizeClickUpWebhookApiResponse(webhook, config);
+    if (remote.publicUrl !== config.webhook.publicUrl) continue;
+    if (!clickUpWebhookLocationCompatible(webhook, config)) continue;
+    if (!isClickUpWebhookStateActive(remote, config)) continue;
+    return remote;
+  }
+  return null;
+}
 async function validateClickUpWebhookState(state, config, clickupClient = null) {
   if (!isClickUpWebhookStateActive(state, config)) return { valid: false, reason: "state_incomplete" };
   if (clickupClient?.listWebhooks) {
@@ -9041,8 +9064,19 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
   const existingValidation = await validateClickUpWebhookState(existing, config, clickupClient);
   if (existingValidation.valid) {
     const state = writeClickUpWebhookState(worktree, { ...existingValidation.state, recentEventKeys: existing.recentEventKeys || [] }, config);
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: existingValidation.mode });
     return { active: true, valid: true, mode: existingValidation.mode, limitation: existingValidation.limitation, state };
   }
+  if (existing.webhookId && clickupClient?.deleteWebhook) {
+    await deleteClickUpWebhookBestEffort({ webhookId: existing.webhookId, clickupClient, worktree, reason: existingValidation.reason || "startup_self_heal" });
+    markClickUpWebhookInactive(worktree, existing, config);
+  }
+  const reusableRemote = await findReusableClickUpWebhook(config, clickupClient);
+  if (reusableRemote) {
+    const state = writeClickUpWebhookState(worktree, { ...reusableRemote, recentEventKeys: existing.recentEventKeys || [] }, config);
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: "remote_discovered" });
+    return { active: true, valid: true, mode: "remote_discovered", state };
+  }
   if (!clickupClient?.createWebhook) {
     return { active: false, valid: false, reason: "clickup_client_unavailable", state: existing };
   }
@@ -9062,15 +9096,12 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
     }
   }
   if (!createdValidation.valid) {
-    if (stateForValidation.webhookId && clickupClient?.deleteWebhook) {
-      try {
-        await clickupClient.deleteWebhook(stateForValidation.webhookId);
-      } catch {
-      }
-    }
+    await deleteClickUpWebhookBestEffort({ webhookId: stateForValidation.webhookId, clickupClient, worktree, reason: "created_state_invalid" });
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_create_invalid", webhookId: stateForValidation.webhookId, reason: createdValidation.reason });
     return { active: false, valid: false, reason: "created_state_invalid", validation: createdValidation, state: stateForValidation };
   }
   const next = writeClickUpWebhookState(worktree, createdValidation.state || stateForValidation, config);
+  clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_created", webhookId: next.webhookId, mode: createdValidation.mode || "created" });
   const mode = createdValidation.mode === "created_pending_remote_validation" ? "created_pending_remote_validation" : clickupClient?.listWebhooks ? "created_remote_validated" : "created";
   return { active: true, valid: true, mode, limitation: createdValidation.limitation, state: next };
 }
@@ -9253,6 +9284,93 @@ function appendClickUpWebhookLocalLog(worktree, entry) {
   fs2.appendFileSync(logPath, `${JSON.stringify(safeEntry)}
 `, "utf8");
 }
+function clickUpWebhookLifecycleLog(worktree, entry) {
+  try {
+    appendClickUpWebhookLocalLog(worktree, { scope: "lifecycle", ...entry });
+  } catch {
+  }
+}
+function promiseWithTimeout(promise, timeoutMs, timeoutValue) {
+  let timeout;
+  return Promise.race([
+    Promise.resolve(promise),
+    new Promise((resolve) => {
+      timeout = setTimeout(() => resolve(timeoutValue), Math.max(1, Number(timeoutMs) || CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS));
+    })
+  ]).finally(() => clearTimeout(timeout));
+}
+function closeClickUpWebhookServer(server) {
+  if (!server || typeof server.close !== "function") return Promise.resolve({ ok: true, skipped: true });
+  return new Promise((resolve) => {
+    try {
+      server.close((error) => resolve(error ? { ok: false, error: error.message } : { ok: true }));
+    } catch (error) {
+      resolve({ ok: false, error: error.message });
+    }
+  });
+}
+function managedClickUpWebhookKey({ worktree, state, config } = {}) {
+  return [path2.resolve(worktree || process.cwd()), state?.webhookId || "", config?.webhook?.publicUrl || ""].join("|");
+}
+async function deleteClickUpWebhookBestEffort({ webhookId, clickupClient, worktree, reason = "cleanup" } = {}) {
+  const id = String(webhookId || "").trim();
+  if (!id || !clickupClient?.deleteWebhook) return { ok: false, skipped: true, reason: "delete_unavailable" };
+  try {
+    await clickupClient.deleteWebhook(id);
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_deleted", reason, webhookId: id });
+    return { ok: true };
+  } catch (error) {
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_delete_failed", reason, webhookId: id, message: error.message });
+    return { ok: false, error: error.message };
+  }
+}
+function markClickUpWebhookInactive(worktree, state = {}, config = null) {
+  if (!worktree || !state?.webhookId) return null;
+  return writeClickUpWebhookState(worktree, { ...state, active: false, listener: {}, lastValidatedAt: (/* @__PURE__ */ new Date()).toISOString() }, config);
+}
+async function cleanupManagedClickUpWebhook(entry = {}, { timeoutMs = CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS, reason = "shutdown" } = {}) {
+  if (!entry || entry.cleaning) return { ok: true, skipped: true, reason: "already_cleaning" };
+  entry.cleaning = true;
+  const cleanup = (async () => {
+    clickUpWebhookLifecycleLog(entry.worktree, { type: "cleanup_started", reason, key: entry.key, webhookId: entry.state?.webhookId });
+    const closeResult = await closeClickUpWebhookServer(entry.listener?.server);
+    if (entry.listenerRegistry && entry.listener?.key) entry.listenerRegistry.delete(entry.listener.key);
+    const deleteResult = await deleteClickUpWebhookBestEffort({ webhookId: entry.state?.webhookId, clickupClient: entry.clickupClient, worktree: entry.worktree, reason });
+    if (deleteResult.ok) markClickUpWebhookInactive(entry.worktree, entry.state, entry.config);
+    activeClickUpWebhookLifecycleRegistry.delete(entry.key);
+    clickUpWebhookLifecycleLog(entry.worktree, { type: "cleanup_finished", reason, close_ok: closeResult.ok, delete_ok: deleteResult.ok, delete_reason: deleteResult.reason });
+    return { ok: closeResult.ok !== false && deleteResult.ok !== false, closeResult, deleteResult };
+  })();
+  const result = await promiseWithTimeout(cleanup, timeoutMs, { ok: false, timeout: true, reason: "cleanup_timeout" });
+  if (result?.timeout) clickUpWebhookLifecycleLog(entry.worktree, { type: "cleanup_timeout", reason, webhookId: entry.state?.webhookId });
+  return result;
+}
+function registerClickUpWebhookLifecycle({ config, state, worktree, clickupClient, listener, listenerRegistry = activeClickUpWebhookListeners } = {}) {
+  if (!isClickUpWebhookStateActive(state, config)) return null;
+  const key = managedClickUpWebhookKey({ worktree, state, config });
+  const entry = { key, config, state, worktree, clickupClient, listener, listenerRegistry, registeredAt: (/* @__PURE__ */ new Date()).toISOString() };
+  activeClickUpWebhookLifecycleRegistry.set(key, entry);
+  installClickUpWebhookSignalHandlers();
+  clickUpWebhookLifecycleLog(worktree, { type: "lifecycle_registered", key, webhookId: state.webhookId });
+  return entry;
+}
+function installClickUpWebhookSignalHandlers() {
+  const globalState = globalThis[CLICKUP_WEBHOOK_SIGNAL_STATE] || { installed: false, running: false };
+  if (globalState.installed) return;
+  const handler = (signal) => {
+    if (globalState.running) return;
+    globalState.running = true;
+    const timeoutMs = CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS;
+    const cleanup = Promise.allSettled([...activeClickUpWebhookLifecycleRegistry.values()].map((entry) => cleanupManagedClickUpWebhook(entry, { timeoutMs, reason: signal })));
+    promiseWithTimeout(cleanup, timeoutMs + 500, { timeout: true }).finally(() => {
+      process.exit(signal === "SIGINT" ? 130 : 143);
+    });
+  };
+  process.once("SIGTERM", handler);
+  process.once("SIGINT", handler);
+  globalState.installed = true;
+  globalThis[CLICKUP_WEBHOOK_SIGNAL_STATE] = globalState;
+}
 function redactClickUpWebhookAuditValue(value, secretValues = []) {
   if (typeof value === "string") {
     return secretValues.reduce((next, secret) => secret ? next.split(secret).join(CLICKUP_WEBHOOK_REDACTED) : next, value);
@@ -10566,25 +10684,35 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
   let clickUpWebhookActive = clickUpWebhookRuntime.active === true && clickUpWebhookRuntime.valid === true;
   if (clickUpWebhookActive && input.startClickUpWebhookListener !== false) {
     try {
+      const lifecycleClickUpClient = input.clickupClient || createClickUpApiClient(clickUpWebhookValidation.config, input.fetch);
+      const listenerRegistry = input.clickUpWebhookListenerRegistry || activeClickUpWebhookListeners;
+      const listenerState = clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config);
       const listener = startClickUpWebhookListener({
         config: clickUpWebhookValidation.config,
-        state: clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config),
+        state: listenerState,
         worktree,
-        clickupClient: input.clickupClient || createClickUpApiClient(clickUpWebhookValidation.config, input.fetch),
+        clickupClient: lifecycleClickUpClient,
         openCodeClient: input.client,
-        listenerRegistry: input.clickUpWebhookListenerRegistry || activeClickUpWebhookListeners
+        listenerRegistry
       });
       const readyListener = listener.readyPromise ? await listener.readyPromise : listener;
       if (readyListener.active && readyListener.ready !== false) {
-        writeClickUpWebhookState(worktree, {
-          ...clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config),
+        const activeState = writeClickUpWebhookState(worktree, {
+          ...listenerState,
           listener: { bindHost: clickUpWebhookValidation.config.webhook.bindHost, bindPort: clickUpWebhookValidation.config.webhook.bindPort, startedAt: (/* @__PURE__ */ new Date()).toISOString() }
         }, clickUpWebhookValidation.config);
+        registerClickUpWebhookLifecycle({ config: clickUpWebhookValidation.config, state: activeState, worktree, clickupClient: lifecycleClickUpClient, listener: readyListener, listenerRegistry });
       } else {
+        await deleteClickUpWebhookBestEffort({ webhookId: listenerState.webhookId, clickupClient: lifecycleClickUpClient, worktree, reason: readyListener.reason || "listener_unavailable" });
+        markClickUpWebhookInactive(worktree, listenerState, clickUpWebhookValidation.config);
         clickUpWebhookActive = false;
         clickUpWebhookRuntime = { ...clickUpWebhookRuntime, active: false, valid: false, reason: readyListener.reason || "listener_unavailable" };
       }
     } catch (error) {
+      const failureState = clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config);
+      const failureClient = input.clickupClient || createClickUpApiClient(clickUpWebhookValidation.config, input.fetch);
+      await deleteClickUpWebhookBestEffort({ webhookId: failureState.webhookId, clickupClient: failureClient, worktree, reason: "listener_failed" });
+      markClickUpWebhookInactive(worktree, failureState, clickUpWebhookValidation.config);
       clickUpWebhookActive = false;
       clickUpWebhookRuntime = { ...clickUpWebhookRuntime, active: false, valid: false, reason: "listener_failed", error: error.message };
       appendClickUpWebhookLocalLog(worktree, { type: "listener_failed", message: error.message });
@@ -11139,7 +11267,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 export {
   OptimaPlugin as default
 };

package/dist/sanitize_cli.js

@@ -8024,6 +8024,9 @@ var REPO_LOCAL_POLICIES_README = [
 ].join("\n");
 var activeWorkflows = /* @__PURE__ */ new Map();
 var activeClickUpWebhookListeners = /* @__PURE__ */ new Map();
+var activeClickUpWebhookLifecycleRegistry = /* @__PURE__ */ new Map();
+var CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS = 8e3;
+var CLICKUP_WEBHOOK_SIGNAL_STATE = Symbol.for("opencode-optima.clickup-webhook.signal-state");
 var activeClickUpTaskRoutes = /* @__PURE__ */ new Map();
 var objectIdentityMap = /* @__PURE__ */ new WeakMap();
 var objectIdentitySequence = 0;
@@ -9024,6 +9027,26 @@ function clickUpWebhookListItems(response = {}) {
   if (Array.isArray(response?.data?.webhooks)) return response.data.webhooks;
   return [];
 }
+function clickUpWebhookLocationCompatible(webhook = {}, config = {}) {
+  const location = config?.webhook?.location || {};
+  for (const key of ["space_id", "folder_id", "list_id"]) {
+    const expected = String(location[key] || "").trim();
+    if (expected && String(webhook[key] || webhook.location?.[key] || "").trim() !== expected) return false;
+  }
+  return true;
+}
+async function findReusableClickUpWebhook(config, clickupClient = null) {
+  if (!clickupClient?.listWebhooks) return null;
+  const listed = await clickupClient.listWebhooks({ teamId: config.teamId });
+  for (const webhook of clickUpWebhookListItems(listed)) {
+    const remote = normalizeClickUpWebhookApiResponse(webhook, config);
+    if (remote.publicUrl !== config.webhook.publicUrl) continue;
+    if (!clickUpWebhookLocationCompatible(webhook, config)) continue;
+    if (!isClickUpWebhookStateActive(remote, config)) continue;
+    return remote;
+  }
+  return null;
+}
 async function validateClickUpWebhookState(state, config, clickupClient = null) {
   if (!isClickUpWebhookStateActive(state, config)) return { valid: false, reason: "state_incomplete" };
   if (clickupClient?.listWebhooks) {
@@ -9048,8 +9071,19 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
   const existingValidation = await validateClickUpWebhookState(existing, config, clickupClient);
   if (existingValidation.valid) {
     const state = writeClickUpWebhookState(worktree, { ...existingValidation.state, recentEventKeys: existing.recentEventKeys || [] }, config);
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: existingValidation.mode });
     return { active: true, valid: true, mode: existingValidation.mode, limitation: existingValidation.limitation, state };
   }
+  if (existing.webhookId && clickupClient?.deleteWebhook) {
+    await deleteClickUpWebhookBestEffort({ webhookId: existing.webhookId, clickupClient, worktree, reason: existingValidation.reason || "startup_self_heal" });
+    markClickUpWebhookInactive(worktree, existing, config);
+  }
+  const reusableRemote = await findReusableClickUpWebhook(config, clickupClient);
+  if (reusableRemote) {
+    const state = writeClickUpWebhookState(worktree, { ...reusableRemote, recentEventKeys: existing.recentEventKeys || [] }, config);
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_reused", webhookId: state.webhookId, mode: "remote_discovered" });
+    return { active: true, valid: true, mode: "remote_discovered", state };
+  }
   if (!clickupClient?.createWebhook) {
     return { active: false, valid: false, reason: "clickup_client_unavailable", state: existing };
   }
@@ -9069,15 +9103,12 @@ async function ensureClickUpWebhookSubscription({ validation, worktree, clickupC
     }
   }
   if (!createdValidation.valid) {
-    if (stateForValidation.webhookId && clickupClient?.deleteWebhook) {
-      try {
-        await clickupClient.deleteWebhook(stateForValidation.webhookId);
-      } catch {
-      }
-    }
+    await deleteClickUpWebhookBestEffort({ webhookId: stateForValidation.webhookId, clickupClient, worktree, reason: "created_state_invalid" });
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_create_invalid", webhookId: stateForValidation.webhookId, reason: createdValidation.reason });
     return { active: false, valid: false, reason: "created_state_invalid", validation: createdValidation, state: stateForValidation };
   }
   const next = writeClickUpWebhookState(worktree, createdValidation.state || stateForValidation, config);
+  clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_created", webhookId: next.webhookId, mode: createdValidation.mode || "created" });
   const mode = createdValidation.mode === "created_pending_remote_validation" ? "created_pending_remote_validation" : clickupClient?.listWebhooks ? "created_remote_validated" : "created";
   return { active: true, valid: true, mode, limitation: createdValidation.limitation, state: next };
 }
@@ -9260,6 +9291,93 @@ function appendClickUpWebhookLocalLog(worktree, entry) {
   fs2.appendFileSync(logPath, `${JSON.stringify(safeEntry)}
 `, "utf8");
 }
+function clickUpWebhookLifecycleLog(worktree, entry) {
+  try {
+    appendClickUpWebhookLocalLog(worktree, { scope: "lifecycle", ...entry });
+  } catch {
+  }
+}
+function promiseWithTimeout(promise, timeoutMs, timeoutValue) {
+  let timeout;
+  return Promise.race([
+    Promise.resolve(promise),
+    new Promise((resolve) => {
+      timeout = setTimeout(() => resolve(timeoutValue), Math.max(1, Number(timeoutMs) || CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS));
+    })
+  ]).finally(() => clearTimeout(timeout));
+}
+function closeClickUpWebhookServer(server) {
+  if (!server || typeof server.close !== "function") return Promise.resolve({ ok: true, skipped: true });
+  return new Promise((resolve) => {
+    try {
+      server.close((error) => resolve(error ? { ok: false, error: error.message } : { ok: true }));
+    } catch (error) {
+      resolve({ ok: false, error: error.message });
+    }
+  });
+}
+function managedClickUpWebhookKey({ worktree, state, config } = {}) {
+  return [path2.resolve(worktree || process.cwd()), state?.webhookId || "", config?.webhook?.publicUrl || ""].join("|");
+}
+async function deleteClickUpWebhookBestEffort({ webhookId, clickupClient, worktree, reason = "cleanup" } = {}) {
+  const id = String(webhookId || "").trim();
+  if (!id || !clickupClient?.deleteWebhook) return { ok: false, skipped: true, reason: "delete_unavailable" };
+  try {
+    await clickupClient.deleteWebhook(id);
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_deleted", reason, webhookId: id });
+    return { ok: true };
+  } catch (error) {
+    clickUpWebhookLifecycleLog(worktree, { type: "remote_webhook_delete_failed", reason, webhookId: id, message: error.message });
+    return { ok: false, error: error.message };
+  }
+}
+function markClickUpWebhookInactive(worktree, state = {}, config = null) {
+  if (!worktree || !state?.webhookId) return null;
+  return writeClickUpWebhookState(worktree, { ...state, active: false, listener: {}, lastValidatedAt: (/* @__PURE__ */ new Date()).toISOString() }, config);
+}
+async function cleanupManagedClickUpWebhook(entry = {}, { timeoutMs = CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS, reason = "shutdown" } = {}) {
+  if (!entry || entry.cleaning) return { ok: true, skipped: true, reason: "already_cleaning" };
+  entry.cleaning = true;
+  const cleanup = (async () => {
+    clickUpWebhookLifecycleLog(entry.worktree, { type: "cleanup_started", reason, key: entry.key, webhookId: entry.state?.webhookId });
+    const closeResult = await closeClickUpWebhookServer(entry.listener?.server);
+    if (entry.listenerRegistry && entry.listener?.key) entry.listenerRegistry.delete(entry.listener.key);
+    const deleteResult = await deleteClickUpWebhookBestEffort({ webhookId: entry.state?.webhookId, clickupClient: entry.clickupClient, worktree: entry.worktree, reason });
+    if (deleteResult.ok) markClickUpWebhookInactive(entry.worktree, entry.state, entry.config);
+    activeClickUpWebhookLifecycleRegistry.delete(entry.key);
+    clickUpWebhookLifecycleLog(entry.worktree, { type: "cleanup_finished", reason, close_ok: closeResult.ok, delete_ok: deleteResult.ok, delete_reason: deleteResult.reason });
+    return { ok: closeResult.ok !== false && deleteResult.ok !== false, closeResult, deleteResult };
+  })();
+  const result = await promiseWithTimeout(cleanup, timeoutMs, { ok: false, timeout: true, reason: "cleanup_timeout" });
+  if (result?.timeout) clickUpWebhookLifecycleLog(entry.worktree, { type: "cleanup_timeout", reason, webhookId: entry.state?.webhookId });
+  return result;
+}
+function registerClickUpWebhookLifecycle({ config, state, worktree, clickupClient, listener, listenerRegistry = activeClickUpWebhookListeners } = {}) {
+  if (!isClickUpWebhookStateActive(state, config)) return null;
+  const key = managedClickUpWebhookKey({ worktree, state, config });
+  const entry = { key, config, state, worktree, clickupClient, listener, listenerRegistry, registeredAt: (/* @__PURE__ */ new Date()).toISOString() };
+  activeClickUpWebhookLifecycleRegistry.set(key, entry);
+  installClickUpWebhookSignalHandlers();
+  clickUpWebhookLifecycleLog(worktree, { type: "lifecycle_registered", key, webhookId: state.webhookId });
+  return entry;
+}
+function installClickUpWebhookSignalHandlers() {
+  const globalState = globalThis[CLICKUP_WEBHOOK_SIGNAL_STATE] || { installed: false, running: false };
+  if (globalState.installed) return;
+  const handler = (signal) => {
+    if (globalState.running) return;
+    globalState.running = true;
+    const timeoutMs = CLICKUP_WEBHOOK_CLEANUP_TIMEOUT_MS;
+    const cleanup = Promise.allSettled([...activeClickUpWebhookLifecycleRegistry.values()].map((entry) => cleanupManagedClickUpWebhook(entry, { timeoutMs, reason: signal })));
+    promiseWithTimeout(cleanup, timeoutMs + 500, { timeout: true }).finally(() => {
+      process.exit(signal === "SIGINT" ? 130 : 143);
+    });
+  };
+  process.once("SIGTERM", handler);
+  process.once("SIGINT", handler);
+  globalState.installed = true;
+  globalThis[CLICKUP_WEBHOOK_SIGNAL_STATE] = globalState;
+}
 function redactClickUpWebhookAuditValue(value, secretValues = []) {
   if (typeof value === "string") {
     return secretValues.reduce((next, secret) => secret ? next.split(secret).join(CLICKUP_WEBHOOK_REDACTED) : next, value);
@@ -10573,25 +10691,35 @@ async function OptimaPlugin(input = {}, pluginOptions = {}) {
   let clickUpWebhookActive = clickUpWebhookRuntime.active === true && clickUpWebhookRuntime.valid === true;
   if (clickUpWebhookActive && input.startClickUpWebhookListener !== false) {
     try {
+      const lifecycleClickUpClient = input.clickupClient || createClickUpApiClient(clickUpWebhookValidation.config, input.fetch);
+      const listenerRegistry = input.clickUpWebhookListenerRegistry || activeClickUpWebhookListeners;
+      const listenerState = clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config);
       const listener = startClickUpWebhookListener({
         config: clickUpWebhookValidation.config,
-        state: clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config),
+        state: listenerState,
         worktree,
-        clickupClient: input.clickupClient || createClickUpApiClient(clickUpWebhookValidation.config, input.fetch),
+        clickupClient: lifecycleClickUpClient,
         openCodeClient: input.client,
-        listenerRegistry: input.clickUpWebhookListenerRegistry || activeClickUpWebhookListeners
+        listenerRegistry
       });
       const readyListener = listener.readyPromise ? await listener.readyPromise : listener;
       if (readyListener.active && readyListener.ready !== false) {
-        writeClickUpWebhookState(worktree, {
-          ...clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config),
+        const activeState = writeClickUpWebhookState(worktree, {
+          ...listenerState,
           listener: { bindHost: clickUpWebhookValidation.config.webhook.bindHost, bindPort: clickUpWebhookValidation.config.webhook.bindPort, startedAt: (/* @__PURE__ */ new Date()).toISOString() }
         }, clickUpWebhookValidation.config);
+        registerClickUpWebhookLifecycle({ config: clickUpWebhookValidation.config, state: activeState, worktree, clickupClient: lifecycleClickUpClient, listener: readyListener, listenerRegistry });
       } else {
+        await deleteClickUpWebhookBestEffort({ webhookId: listenerState.webhookId, clickupClient: lifecycleClickUpClient, worktree, reason: readyListener.reason || "listener_unavailable" });
+        markClickUpWebhookInactive(worktree, listenerState, clickUpWebhookValidation.config);
         clickUpWebhookActive = false;
         clickUpWebhookRuntime = { ...clickUpWebhookRuntime, active: false, valid: false, reason: readyListener.reason || "listener_unavailable" };
       }
     } catch (error) {
+      const failureState = clickUpWebhookRuntime.state || readClickUpWebhookState(worktree, clickUpWebhookValidation.config);
+      const failureClient = input.clickupClient || createClickUpApiClient(clickUpWebhookValidation.config, input.fetch);
+      await deleteClickUpWebhookBestEffort({ webhookId: failureState.webhookId, clickupClient: failureClient, worktree, reason: "listener_failed" });
+      markClickUpWebhookInactive(worktree, failureState, clickUpWebhookValidation.config);
       clickUpWebhookActive = false;
       clickUpWebhookRuntime = { ...clickUpWebhookRuntime, active: false, valid: false, reason: "listener_failed", error: error.message };
       appendClickUpWebhookLocalLog(worktree, { type: "listener_failed", message: error.message });
@@ -11146,7 +11274,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
+OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, startClickUpWebhookListener, validateClickUpWebhookState, verifyClickUpSignature, writeClickUpWebhookState, decideClickUpStatusAction, deriveClickUpBranchName, deriveClickUpPendingSubtaskBranch, deriveClickUpPrTarget, deriveClickUpWorktree, determineClickUpMergeAuthority, ensureOptimaGitignoreRules, explicitSafeInputWorktree, finalApprovalAssignees, formatValidationResult, isIgnoredClickUpTaskType, isOptimaPluginPackageWorktree, isSafeWritableDirectory, loadHumansRegistry, mergeClickUpAgentMetadata, mergeClickUpSessionMetadata, migrateLegacyOptimaLayout, normalizeAgentMetadataJson, normalizeClickUpStatus, normalizeClickUpTaskType, normalizePromptResponseParts, normalizeWorkflowTaskPath, parseClickUpSubtasksMarkdown, parseHumansRegistry, parseMarkdownArtifact, parseMarkdownSections, preEstimateClickUpWork, readMarkdownArtifact, resolveHumanRoles, resolveSafeWorktree, safeWorktreeOrFailure, stripRawLogSections, validateMainWorkspaceBranchSafety, workflowFinalMessageFromPromptResponse };
 
 // src/sanitize_cli.js
 var { migrateLegacyOptimaLayout: migrateLegacyOptimaLayout2 } = OptimaPlugin.__internals;

package/package.json

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

package/policies/README.md

@@ -1,62 +0,0 @@
-# Optima Policies
-
-This package-internal directory contains bundled fallback policy assets. Optima target repositories should put repo-local policy overrides in `.optima/policies/`, not in a root `policies/` directory.
-
-## How Policy Resolution Works
-
-For any `<include:policy:<file>.md>` include, Optima resolves policy files in this order:
-
-1. `.optima/policies/<file>.md`
-2. bundled plugin default `policies/<file>.md`
-
-Files under `.optima/.config/generated/policies/` are reference copies only. They are not read directly at runtime.
-
-## Available Policies
-
-- `development-guidelines.md`
-  - Repository-specific engineering rules, stack notes, and implementation conventions.
-  - Used by: `developer`, `technical_architect`, `tech_lead`, `workflow_runner`
-
-- `testing-guidelines.md`
-  - Testing, evidence, regression, and verification conventions.
-  - Used by: `developer`, `qa_engineer`, `tech_lead`, `workflow_runner`
-
-- `documentation-guidelines.md`
-  - Documentation layout, naming, ownership, and update expectations.
-  - Used by all agents through the shared prompt.
-
-- `definition-of-ready.md`
-  - Canonical readiness criteria before execution begins.
-  - Used by all agents through the shared prompt and reflected in task templates.
-
-- `definition-of-done.md`
-  - Canonical completion criteria before closure.
-  - Used by all agents through the shared prompt and reflected in task templates.
-
-- `git-commit-messaging.md`
-  - Commit subject and body rules.
-  - Used by: `tech_lead`, `workflow_runner`
-
-- `product-guidelines.md`
-  - User story, acceptance criteria, terminology, and product-truth conventions.
-  - Used by: `product_manager`, `business_analyst`
-
-- `ui-ux-guidelines.md`
-  - UI review standards and visual quality expectations.
-  - Used by: `ui_ux_designer`
-
-## Customizing A Policy
-
-1. Set `.optima/.config/optima.yaml` `policies.extract_defaults` to `all` if you want reference copies of all bundled defaults.
-2. Inspect `.optima/.config/generated/policies/` for the default files.
-3. Copy the policy you want to customize into `.optima/policies/`.
-4. Edit the copied file. The repo-local version will override the plugin default automatically.
-
-## Policy Extraction
-
-`policies.extract_defaults` supports:
-
-- `none`: do not generate reference policy files
-- `all`: write all bundled default policy files to `.optima/.config/generated/policies/`
-
-Only files in `.optima/policies/` affect runtime prompt behavior.

package/policies/codemap.yml

@@ -1,12 +0,0 @@
-scope: module
-parent: ../.optima/codemap.yml
-sources_of_truth:
-  - path: README.md
-  - path: definition-of-done.md
-  - path: definition-of-ready.md
-  - path: development-guidelines.md
-  - path: documentation-guidelines.md
-  - path: git-commit-messaging.md
-  - path: product-guidelines.md
-  - path: testing-guidelines.md
-  - path: ui-ux-guidelines.md

package/policies/definition-of-done.md

@@ -1,27 +0,0 @@
-# Definition Of Done
-
-A task is done only when the implementation, verification, documentation, and workflow closure requirements are all complete.
-
-## Completion Criteria
-
-- All in-scope acceptance criteria are satisfied or explicitly marked blocked with documented reason.
-- Required tests, builds, and other verification commands pass according to the repository testing policy.
-- Required evidence and verification artifacts are recorded.
-- Product and technical documentation impact is resolved according to the repository documentation policy.
-- Relevant CodeMap updates are completed when the changed code affects entrypoints, wiring, or maintained source structure.
-- Task files, discussion references, and workflow registries are updated as needed.
-- `.optima/` task, todo, evidence, SCR/docs, registry, discussion, and runtime tracking artifacts are written before the final commit.
-- The authorized review and closure roles have completed their required checks.
-- The final committed state includes all required code, documentation, `.optima` closure artifacts, and registry updates.
-
-## Not Done Conditions
-
-- Any required test or build fails.
-- Evidence is missing for claimed verification.
-- Documentation or CodeMap impact remains unresolved.
-- Acceptance criteria are incomplete, unclear, or unverified.
-- Required finalization or archiving steps are missing.
-
-## Operational Rule
-
-A task must not be marked complete while any Definition of Done item remains open.

package/policies/definition-of-ready.md

@@ -1,27 +0,0 @@
-# Definition Of Ready
-
-A task is ready to begin only when the repository has enough information to execute safely and efficiently without inventing scope.
-
-## Readiness Criteria
-
-- Scope is clear, bounded, and appropriate for the task's declared complexity.
-- The task objective is specific enough that the next responsible agent can act without guessing intent.
-- Acceptance criteria are present, testable, and aligned with the stated scope.
-- Complexity, track, and slice are set correctly for the work being requested.
-- Required dependencies, assumptions, blockers, and open questions are either resolved or explicitly recorded.
-- Required pre-sync specialists have reviewed the task definition according to the active task model.
-- An approved SCR exists whenever the workflow requires one.
-- The relevant repository areas are identified well enough to begin safe investigation, design, or implementation.
-
-## Not Ready Conditions
-
-- Requirements are ambiguous or contradictory.
-- Acceptance criteria are missing or too vague to verify.
-- The task is larger or riskier than its current routing metadata suggests.
-- Required specialist review has not happened yet.
-- A required SCR is missing or not approved.
-- Critical blockers or dependencies are unknown or unrecorded.
-
-## Operational Rule
-
-If the task fails the Definition of Ready, execution should pause until the missing information is resolved or explicitly recorded for follow-up.

package/policies/development-guidelines.md

@@ -1,21 +0,0 @@
-# Development Guidelines
-
-These defaults are intended to be customized per repository when needed.
-
-## Stack Notes
-
-- Language: define in the repository if needed.
-- Runtime / Framework: define in the repository if needed.
-- Frontend stack: define in the repository if needed.
-- Testing stack: define in the repository if needed.
-- Database / storage: define in the repository if needed.
-
-## Default Engineering Conventions
-
-- Prefer clear module or feature boundaries over ad-hoc file placement.
-- Keep external integrations behind stable interfaces or wrappers when practical.
-- Update `.gitignore` when repository changes introduce generated, temporary, or sensitive files.
-- Prefer stable dependency versions unless repository compatibility requires otherwise.
-- Use dependency-provided setup or initialization utilities when they are the standard way to integrate the dependency safely.
-- Document meaningful architecture changes in the repository's documentation before or alongside implementation.
-- Keep code changes aligned with existing repository conventions unless the repository policy explicitly changes them.

package/policies/documentation-guidelines.md

@@ -1,39 +0,0 @@
-# Documentation Guidelines
-
-## Documentation Goals
-
-- Keep documentation easy to locate and update.
-- Separate steady-state truth from change proposals and workflow records.
-- Update documentation in the same change set as the implementation whenever the documented truth changes.
-
-## Default Documentation Layout
-
-- `docs/product/`: whole-product truth and top-level feature inventory
-- `docs/domains/`: stable product-area truth shared by multiple features
-- `docs/features/`: one concrete capability or feature specification
-- `docs/architecture/`: technical design, contracts, and cross-cutting decisions
-- `.optima/docs/scrs/`: proposed and approved changes, not steady-state truth
-
-## Update Expectations
-
-Update the relevant documentation when work changes:
-
-- product behavior, terminology, or feature inventory
-- architecture, interfaces, or technical invariants
-- feature specifications or acceptance criteria
-- documentation ownership, naming, or structure conventions
-
-## Default Ownership
-
-- Business Analyst: product, domain, and feature truth from the product perspective
-- Technical Architect: architecture truth and technical design documentation
-- Product Manager: verifies documentation closure during workflow execution
-- Developer / Tech Lead / QA: contribute technical accuracy when implementation changes documented truth
-
-## Default Repository Matrix
-
-- Product overview: `docs/product/PRODUCT_OVERVIEW.md`
-- Features list: `docs/product/FEATURES_LIST.md`
-- Architecture: `docs/architecture/TECHNICAL_ARCHITECTURE.md`
-- Feature specification: `docs/features/<feature>/SPECIFICATION.md`
-- CodeMap updates: relevant `codemap.yml` files for changed code areas

package/policies/git-commit-messaging.md

@@ -1,14 +0,0 @@
-# Git Commit Messaging
-
-Use a concise subject line in this format:
-
-`<type>: <optional-task-id> <short summary>`
-
-Examples:
-
-- `docs: update workflow guidance`
-- `fix: TASK-014 correct task archive logic`
-
-Always include a brief body that explains what the commit is for and why the change exists.
-
-If the commit is associated with a task, include the task ID in the subject when practical.

package/policies/product-guidelines.md

@@ -1,20 +0,0 @@
-# Product Guidelines
-
-## Product Writing Defaults
-
-- Write user stories and requirements in clear, unambiguous language.
-- Keep acceptance criteria specific, testable, and easy to map to verification evidence.
-- Use numbered acceptance criteria (`AC-1`, `AC-2`, ...) for tracked work.
-- Maintain consistent product terminology across SCRs, tasks, and steady-state docs.
-
-## User Story And Acceptance Criteria Conventions
-
-- User stories may use the format: `As a <user>, I want <action>, so that <benefit>.`
-- Acceptance criteria should describe observable behavior or outcomes rather than implementation details.
-- When requirements are incomplete or ambiguous, stop and push for clarification instead of inventing scope.
-
-## Product Truth Stewardship
-
-- Keep product documentation cross-linked and internally consistent.
-- When behavior changes, update the relevant product-facing docs and SCR registries.
-- If the repository establishes domain or feature naming conventions, apply them consistently.

package/policies/testing-guidelines.md

@@ -1,30 +0,0 @@
-# Testing Guidelines
-
-## Test Levels
-
-1. Unit tests verify isolated logic, functions, and classes.
-2. Integration tests verify interactions between multiple modules or external services.
-3. End-to-end tests verify real user or system flows through the product.
-4. Manual verification is allowed for visual or interaction checks that cannot be automated effectively.
-
-## Verification Policy
-
-- All automated tests must pass. No expected skips or tolerated failures are allowed by default.
-- Tests should live close to the code they verify unless the repository uses a clearly defined alternative structure.
-- Every `implementation` task must produce reviewable verification artifacts under `.optima/evidences/<task_id>/`.
-- Do not create or reference a root `evidences/` folder; implementation evidence belongs only under `.optima/evidences/<task_id>/`.
-- Verification artifacts should map back to the task's numbered acceptance criteria.
-- Run the relevant regression coverage before handing implementation back for technical review.
-
-## Evidence Defaults
-
-By default, `.optima/evidences/<task_id>/` implementation evidence should include:
-
-- `SUMMARY.md` with a short summary and numbered acceptance criteria coverage
-- `logs/` with command output or logs for relevant automated checks
-- `screenshots/` with UI screenshots or visual review artifacts when UI changes are involved
-
-## Non-Implementation Outputs
-
-- `investigation` tasks should produce findings, reproduction notes, useful logs, and a recommended next step.
-- `spec` tasks should produce SCR or documentation updates that define the accepted change and its impact.

package/policies/ui-ux-guidelines.md

@@ -1,33 +0,0 @@
-# UI/UX Guidelines
-
-## Core Principles
-
-1. Prioritize ease of use, accessibility, and intuitive navigation.
-2. Aim for a modern, clean, and polished visual design.
-3. Keep UI elements visually consistent with the repository's design language.
-4. Use layout, color, and typography to create clear visual hierarchy.
-
-## Review Workflow
-
-- Define the intended screens, interactions, and layout before implementation when UI work is involved.
-- Review screenshots and other visual evidence under `.optima/evidences/<task_id>/` after implementation; do not look for a root evidence folder.
-- Evaluate the result visually rather than by reading code.
-- If the available evidence is insufficient, say so clearly and ask for better screenshots or artifacts.
-
-## Visual Quality Checklist
-
-Reject or request fixes when you see:
-
-- obvious misalignment against the page or component grid
-- inconsistent spacing between similar elements
-- weak typography hierarchy that makes the screen hard to scan
-- interactive elements that do not look interactive
-- low-contrast text or other readability issues
-- cluttered, dated, or visibly unpolished presentation
-
-## Required Fix Triggers
-
-- overlapping UI or clipped text
-- missing key interaction steps that were part of the intended flow
-- ignored design system conventions for color, typography, or spacing
-- an overall result that feels amateur or not ready for users