@defend-tech/opencode-optima 0.1.32 → 0.1.34

package/assets/agents/workflow_product_manager.md

@@ -6,7 +6,6 @@ tools:
   optima_validate: true
   optima_start_discussion: true
   optima_stop_discussion: true
-  optima_run_workflow: true
   optima_prompt_workflow: true
 ---
 You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
@@ -27,6 +26,8 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 - Definition content must be complete: scope, AC, decomposition, owners, test strategy, evidence expectations, handoff rules, open risks. Empty docs or comment-only plans are invalid.
 - Final Documentation is separate delivered behavior/technical/user documentation; Validator/QA fails validation when required final docs are missing or stale.
 - Store `agent_metadata` JSON with session IDs per agent/type/task/subtask and update it whenever an agent session starts or responsibility changes.
+- You are already the ClickUp task workflow; never launch nested/generic `optima_run_workflow` sessions.
+- Use `optima_prompt_workflow` only to prompt/resume an existing task-owned `workflow_runner` session whose session id is already registered in `agent_metadata` for the current task/subtask. Do not use it to launch generic workflows or unregistered sessions.
 - Use `Optima ClickUp-first Workflow Framework` as the steady-state guide when present.
 
 ## Webhook And Intake
@@ -61,7 +62,7 @@ You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 
 ## Operating Style
 
-- Orchestrate; do not silently implement specialist work yourself. Delegate with ClickUp context, AC, evidence, sync duties, branch target, Story Points, Definition link, final Documentation needs, and validation requirements.
+- Orchestrate; do not silently implement specialist work yourself. Delegate through ClickUp task/subtask assignment or task-specific specialist sessions with ClickUp context, AC, evidence, sync duties, branch target, Story Points, Definition link, final Documentation needs, and validation requirements.
 - Never abandon a PM-assigned task: keep working until unblocked and handed off, or post the stop/blocker/clarification/error as a ClickUp comment, remove Workflow/Product Manager, and assign `CTO` plus `PO` or next owner.
 - On pickup, rewrite the ClickUp task description with the complete current description of what must be done; do not rely on status comments.
 - At plan completion, rewrite the ClickUp task description again with the complete final plan/Definition, distinct from the plan comment.

package/dist/index.js

@@ -7946,8 +7946,8 @@ var LEGACY_NOMADWORKS_DIRNAME = ".nomadworks";
 var LEGACY_ORBITA_DIRNAME = ".orbita";
 var LEGACY_STATICENG_DIRNAME = ".staticeng";
 var OPTIMA_GITIGNORE_RULES = [
-  ".optima/",
-  ".optima/.config/",
+  ".optima/tasks/current.md",
+  ".optima/.config/runtime/*",
   ".optima/**/.env",
   ".optima/**/.env.*",
   ".optima/**/*.env",
@@ -8497,9 +8497,11 @@ function buildClickUpSummaryPayload({ summaryMarkdown = "", summaryPath = "", ta
     ["Open Risks", sectionValue(summarySections, ["Open Risks"])],
     ["Recommended Next Step", sectionValue(summarySections, ["Recommended Next Step"])]
   ];
+  const deliveryPath = summaryPath.includes("docs/delivery/") ? summaryPath : "";
   const contextParts = [
     branchValue ? `- Branch: ${compactMarkdownValue(branchValue)}` : null,
     worktreeValue ? `- Worktree: ${compactMarkdownValue(worktreeValue)}` : null,
+    deliveryPath ? `- Delivery evidence: ${compactMarkdownValue(deliveryPath)}` : null,
     prValue ? `- PR: ${compactMarkdownValue(prValue)}` : null
   ].filter(Boolean);
   const comment = [
@@ -8524,7 +8526,8 @@ function buildClickUpSummaryPayload({ summaryMarkdown = "", summaryPath = "", ta
         recommended_next_step: compactMarkdownValue(sectionValue(summarySections, ["Recommended Next Step"])),
         branch: compactMarkdownValue(branchValue),
         worktree: compactMarkdownValue(worktreeValue),
-        pr: compactMarkdownValue(prValue)
+        pr: compactMarkdownValue(prValue),
+        delivery_evidence_path: compactMarkdownValue(deliveryPath)
       }
     },
     parsed: { summary: summarySections, task: taskSections }
@@ -8535,6 +8538,60 @@ function deriveClickUpWorktree({ baseWorktree = "", taskId, taskType, parentTask
   const root = baseWorktree || process.cwd();
   return path2.join(path2.dirname(root), `${path2.basename(root)}-${branch.replace(/\//g, "-")}`);
 }
+function clickUpCustomFieldValue(task = {}, names = []) {
+  const fields = Array.isArray(task.custom_fields) ? task.custom_fields : [];
+  const wanted = new Set(names.map((name) => normalizeLooseToken(name)));
+  const field = fields.find((item) => wanted.has(normalizeLooseToken(item?.name || item?.id || "")));
+  return field?.value ?? "";
+}
+function clickUpTaskType(task = {}, fallback = "Tarea") {
+  return task.type || task.task_type || task.taskType || clickUpCustomFieldValue(task, ["Type", "Tipo", "Task Type"]) || fallback;
+}
+function clickUpParentTaskId(task = {}) {
+  return task.parent || task.parent_id || task.parentId || task.parent_task_id || task.parentTaskId || "";
+}
+function deliveryEvidencePathForClickUpTask(taskId) {
+  return `docs/delivery/${branchSafeClickUpId(taskId)}/SUMMARY.md`;
+}
+function metadataTaskRouting(metadata = {}) {
+  return isPlainObject(metadata.task) ? metadata.task : {};
+}
+function safeExistingClickUpWorktree({ metadata = {}, branch = "" } = {}) {
+  const taskMetadata = metadataTaskRouting(metadata);
+  const existingWorktree = typeof taskMetadata.worktree === "string" ? taskMetadata.worktree.trim() : "";
+  const existingBranch = typeof taskMetadata.branch === "string" ? taskMetadata.branch.trim() : "";
+  if (!existingWorktree || !path2.isAbsolute(existingWorktree) || !fs2.existsSync(existingWorktree)) return null;
+  try {
+    const stat = fs2.statSync(existingWorktree);
+    if (!stat.isDirectory()) return null;
+    if (branch && existingBranch && existingBranch !== branch) return null;
+    return { branch: existingBranch || branch, worktree: path2.resolve(existingWorktree), reused: true };
+  } catch {
+    return null;
+  }
+}
+function ensureClickUpTaskWorktree({ baseWorktree = "", taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", existingMetadata = {}, runGitFn = runGit, allowNonGitFallback = false } = {}) {
+  const effectiveParent = parentTaskId || taskId;
+  const branch = deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
+  const existing = safeExistingClickUpWorktree({ metadata: existingMetadata, branch });
+  if (existing) return { ...existing, branch };
+  const worktreePath = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
+  if (fs2.existsSync(worktreePath)) return { branch, worktree: path2.resolve(worktreePath), reused: true };
+  if (allowNonGitFallback) {
+    fs2.mkdirSync(worktreePath, { recursive: true });
+    return { branch, worktree: path2.resolve(worktreePath), reused: false, fallback: "non_git" };
+  }
+  const startPoint = (() => {
+    try {
+      runGitFn(baseWorktree, ["rev-parse", "--verify", "dev"]);
+      return "dev";
+    } catch {
+      return "origin/dev";
+    }
+  })();
+  runGitFn(baseWorktree, ["worktree", "add", "-b", branch, worktreePath, startPoint]);
+  return { branch, worktree: path2.resolve(worktreePath), reused: false, startPoint };
+}
 function normalizeClickUpDefinitionDocParent(parent = {}) {
   const docId = String(parent.doc_id || parent.docId || CLICKUP_DEFINITION_DOC_PARENT.doc_id).trim();
   const pageId = String(parent.page_id || parent.pageId || CLICKUP_DEFINITION_DOC_PARENT.page_id).trim();
@@ -8564,6 +8621,7 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       worktree,
       mirror_task_path: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
+      delivery_evidence_path: deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent),
       ...agentMetadata
     }
   });
@@ -8574,7 +8632,8 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     required_first_actions: [
       "Create or reuse the task-specific branch/worktree before planning or writing local .optima mirrors.",
       `Use branch ${branch} from dev and worktree ${worktree} for this task workspace.`,
-      "Write planning state, .optima/tasks/current.md, task mirrors, and evidence only inside the task worktree.",
+      "Write planning state, .optima/tasks/current.md, task mirrors, and local evidence only inside the task worktree.",
+      `Write merge-trackable final evidence under ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}; .optima remains local mirror/staging.`,
       "Do not update the principal dev workspace .optima/tasks/current.md for ClickUp task planning.",
       "If another active task is present in current.md, move to or create this task worktree instead of stopping."
     ],
@@ -8587,13 +8646,14 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     mirror: {
       taskPath: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidenceSummaryPath: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
+      deliveryEvidencePath: deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent),
       workspace: "task_worktree_only",
       principalWorkspaceCurrentMd: "do_not_update",
       currentMdConflictPolicy: "move_to_or_create_task_worktree",
       wouldCreate: true
     },
     clickup: {
-      comment: `Starting task from dev. Branch: ${branch}. Worktree: ${worktree}.`,
+      comment: `Starting task from dev. Branch: ${branch}. Worktree: ${worktree}. Delivery evidence: ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}.`,
       description,
       fields: {
         Definition: definitionContent,
@@ -9384,6 +9444,11 @@ function clickUpPendingSessionKey(metadataKey) {
 function mergeClickUpPendingSessionMetadata(existing, metadataKey, sessionId) {
   return mergeClickUpSessionMetadata(existing, clickUpPendingSessionKey(metadataKey), sessionId);
 }
+function setClickUpTaskRoutingMetadata(existing, routing = {}) {
+  const root = normalizeAgentMetadataJson(existing);
+  root.task = { ...isPlainObject(root.task) ? root.task : {}, ...routing };
+  return JSON.stringify(sortJsonValue(root), null, 2);
+}
 function setClickUpSessionMetadata(existing, metadataKey, sessionId) {
   const root = normalizeAgentMetadataJson(existing);
   const parts = String(metadataKey || CLICKUP_PM_METADATA_KEY).split(".").filter(Boolean);
@@ -9478,16 +9543,20 @@ async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, direct
   if (directBaseUrl) return sendOpenCodeSessionEventDirect({ baseUrl: directBaseUrl, sessionId, text, fetchImpl });
   throw new Error("OpenCode client does not expose session.prompt or session.promptAsync.");
 }
-function formatClickUpWebhookPrompt({ eventType, taskId, payload }) {
+function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", worktree = "", deliveryEvidencePath = "" }) {
   const comment = clickUpCommentFromPayload(payload);
   const commentText = clickUpCommentText(comment).trim();
   return [
     "[ClickUp Webhook Event]",
     `Event: ${eventType}`,
     `Task ID: ${taskId}`,
+    branch ? `Branch: ${branch}` : null,
+    worktree ? `Worktree: ${worktree}` : null,
+    deliveryEvidencePath ? `Delivery evidence path: ${deliveryEvidencePath}` : null,
     commentText ? `Comment: ${commentText}` : null,
     "",
-    "Handle this ClickUp Product Manager event using the ClickUp-first workflow rules. Do not assume broad chat routing; this event passed Optima webhook gates."
+    "Handle this ClickUp Product Manager event using the ClickUp-first workflow rules. Do not assume broad chat routing; this event passed Optima webhook gates.",
+    deliveryEvidencePath ? `Final merge-trackable evidence must be written under ${deliveryEvidencePath}; use .optima only as local mirror/staging.` : null
   ].filter((part) => part !== null).join("\n");
 }
 function appendClickUpWebhookLocalLog(worktree, entry) {
@@ -9666,7 +9735,7 @@ async function withClickUpTaskRouteLock(taskId, operation) {
     if (activeClickUpTaskRoutes.get(key) === current) activeClickUpTaskRoutes.delete(key);
   }
 }
-async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, saveState = null, now = () => /* @__PURE__ */ new Date(), host = os.hostname(), commentLedgerPath = clickUpCommentLedgerPath(worktree) } = {}) {
+async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, ensureTaskWorktree = ensureClickUpTaskWorktree, saveState = null, now = () => /* @__PURE__ */ new Date(), host = os.hostname(), commentLedgerPath = clickUpCommentLedgerPath(worktree) } = {}) {
   const eventType = clickUpEventType(payload);
   const eventKey = clickUpWebhookEventKey(payload);
   const remembered = rememberClickUpWebhookEvent(state, eventKey);
@@ -9714,11 +9783,31 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
   const metadata = normalizeAgentMetadataJson(existingMetadata);
   const existingSessionId = getNestedMetadataValue(metadata, config.routing.metadataKey);
-  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload });
+  const taskType = clickUpTaskType(task);
+  const parentTaskId = clickUpParentTaskId(task) || taskId;
+  const subtaskId = parentTaskId && parentTaskId !== taskId ? taskId : "";
+  let taskRoute;
+  try {
+    taskRoute = ensureTaskWorktree({ baseWorktree: config.basePath, taskId, taskType, parentTaskId, subtaskId, existingMetadata: metadata, allowNonGitFallback: process.env.NODE_ENV === "test" });
+  } catch (error) {
+    const message = `Optima webhook could not create or reuse a task worktree for ${taskId}: ${error.message}`;
+    appendClickUpWebhookLocalLog(worktree, { type: "task_worktree_failed", taskId, message });
+    if (typeof clickupClient?.postTaskComment === "function") await clickupClient.postTaskComment({ taskId, comment: message });
+    return { ok: false, action: "error", reason: "task_worktree_failed", taskId, message };
+  }
+  const deliveryEvidencePath = deliveryEvidencePathForClickUpTask(taskId);
+  const routingMetadata = {
+    branch: taskRoute.branch,
+    worktree: taskRoute.worktree,
+    delivery_evidence_path: deliveryEvidencePath,
+    evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId)}/SUMMARY.md`
+  };
+  const metadataWithRouting = setClickUpTaskRoutingMetadata(existingMetadata, routingMetadata);
+  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath });
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
-      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: config.basePath, agent: config.routing.targetAgent });
+      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: taskRoute.worktree, agent: config.routing.targetAgent });
       if (!String(pendingSessionId || "").startsWith("ses_")) return { ok: false, action: "error", reason: "session_create_failed", taskId };
       if (saveState) {
         saveState({
@@ -9727,14 +9816,14 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
         });
       }
     }
-    const pendingMetadata = mergeClickUpPendingSessionMetadata(existingMetadata, config.routing.metadataKey, pendingSessionId);
+    const pendingMetadata = mergeClickUpPendingSessionMetadata(metadataWithRouting, config.routing.metadataKey, pendingSessionId);
     try {
       await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: pendingMetadata });
     } catch (error) {
       appendClickUpWebhookLocalLog(worktree, { type: "pending_session_metadata_failed", taskId, sessionId: pendingSessionId, message: error.message });
       throw error;
     }
-    await sendSessionEvent(openCodeClient, { sessionId: pendingSessionId, agent: config.routing.targetAgent, text: prompt, directory: config.basePath, opencodeBaseUrl: config.opencode?.baseUrl });
+    await sendSessionEvent(openCodeClient, { sessionId: pendingSessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl });
     const nextMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(pendingMetadata, config.routing.metadataKey, pendingSessionId), config.routing.metadataKey);
     await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
     const { [taskId]: _completedPending, ...remainingPending } = stateToPersist.pendingSessions || {};
@@ -9743,7 +9832,8 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   }
   const sessionId = String(existingSessionId);
   if (await sessionExists(openCodeClient, sessionId)) {
-    await sendSessionEvent(openCodeClient, { sessionId, agent: config.routing.targetAgent, text: prompt, directory: config.basePath, opencodeBaseUrl: config.opencode?.baseUrl });
+    if (typeof clickupClient?.updateTaskMetadata === "function") await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: metadataWithRouting });
+    await sendSessionEvent(openCodeClient, { sessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl });
     return finish({ ok: true, action: "sent_to_existing_session", taskId, sessionId, eventKey });
   }
   const at = now().toISOString();
@@ -11515,7 +11605,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpCommentLedger, readClickUpWebhookState, recordClickUpCommentVersionProcessed, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, stableClickUpCommentVersionMarker, 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, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpCommentLedger, readClickUpWebhookState, recordClickUpCommentVersionProcessed, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, stableClickUpCommentVersionMarker, 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

@@ -7953,8 +7953,8 @@ var LEGACY_NOMADWORKS_DIRNAME = ".nomadworks";
 var LEGACY_ORBITA_DIRNAME = ".orbita";
 var LEGACY_STATICENG_DIRNAME = ".staticeng";
 var OPTIMA_GITIGNORE_RULES = [
-  ".optima/",
-  ".optima/.config/",
+  ".optima/tasks/current.md",
+  ".optima/.config/runtime/*",
   ".optima/**/.env",
   ".optima/**/.env.*",
   ".optima/**/*.env",
@@ -8504,9 +8504,11 @@ function buildClickUpSummaryPayload({ summaryMarkdown = "", summaryPath = "", ta
     ["Open Risks", sectionValue(summarySections, ["Open Risks"])],
     ["Recommended Next Step", sectionValue(summarySections, ["Recommended Next Step"])]
   ];
+  const deliveryPath = summaryPath.includes("docs/delivery/") ? summaryPath : "";
   const contextParts = [
     branchValue ? `- Branch: ${compactMarkdownValue(branchValue)}` : null,
     worktreeValue ? `- Worktree: ${compactMarkdownValue(worktreeValue)}` : null,
+    deliveryPath ? `- Delivery evidence: ${compactMarkdownValue(deliveryPath)}` : null,
     prValue ? `- PR: ${compactMarkdownValue(prValue)}` : null
   ].filter(Boolean);
   const comment = [
@@ -8531,7 +8533,8 @@ function buildClickUpSummaryPayload({ summaryMarkdown = "", summaryPath = "", ta
         recommended_next_step: compactMarkdownValue(sectionValue(summarySections, ["Recommended Next Step"])),
         branch: compactMarkdownValue(branchValue),
         worktree: compactMarkdownValue(worktreeValue),
-        pr: compactMarkdownValue(prValue)
+        pr: compactMarkdownValue(prValue),
+        delivery_evidence_path: compactMarkdownValue(deliveryPath)
       }
     },
     parsed: { summary: summarySections, task: taskSections }
@@ -8542,6 +8545,60 @@ function deriveClickUpWorktree({ baseWorktree = "", taskId, taskType, parentTask
   const root = baseWorktree || process.cwd();
   return path2.join(path2.dirname(root), `${path2.basename(root)}-${branch.replace(/\//g, "-")}`);
 }
+function clickUpCustomFieldValue(task = {}, names = []) {
+  const fields = Array.isArray(task.custom_fields) ? task.custom_fields : [];
+  const wanted = new Set(names.map((name) => normalizeLooseToken(name)));
+  const field = fields.find((item) => wanted.has(normalizeLooseToken(item?.name || item?.id || "")));
+  return field?.value ?? "";
+}
+function clickUpTaskType(task = {}, fallback = "Tarea") {
+  return task.type || task.task_type || task.taskType || clickUpCustomFieldValue(task, ["Type", "Tipo", "Task Type"]) || fallback;
+}
+function clickUpParentTaskId(task = {}) {
+  return task.parent || task.parent_id || task.parentId || task.parent_task_id || task.parentTaskId || "";
+}
+function deliveryEvidencePathForClickUpTask(taskId) {
+  return `docs/delivery/${branchSafeClickUpId(taskId)}/SUMMARY.md`;
+}
+function metadataTaskRouting(metadata = {}) {
+  return isPlainObject(metadata.task) ? metadata.task : {};
+}
+function safeExistingClickUpWorktree({ metadata = {}, branch = "" } = {}) {
+  const taskMetadata = metadataTaskRouting(metadata);
+  const existingWorktree = typeof taskMetadata.worktree === "string" ? taskMetadata.worktree.trim() : "";
+  const existingBranch = typeof taskMetadata.branch === "string" ? taskMetadata.branch.trim() : "";
+  if (!existingWorktree || !path2.isAbsolute(existingWorktree) || !fs2.existsSync(existingWorktree)) return null;
+  try {
+    const stat = fs2.statSync(existingWorktree);
+    if (!stat.isDirectory()) return null;
+    if (branch && existingBranch && existingBranch !== branch) return null;
+    return { branch: existingBranch || branch, worktree: path2.resolve(existingWorktree), reused: true };
+  } catch {
+    return null;
+  }
+}
+function ensureClickUpTaskWorktree({ baseWorktree = "", taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", existingMetadata = {}, runGitFn = runGit, allowNonGitFallback = false } = {}) {
+  const effectiveParent = parentTaskId || taskId;
+  const branch = deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
+  const existing = safeExistingClickUpWorktree({ metadata: existingMetadata, branch });
+  if (existing) return { ...existing, branch };
+  const worktreePath = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
+  if (fs2.existsSync(worktreePath)) return { branch, worktree: path2.resolve(worktreePath), reused: true };
+  if (allowNonGitFallback) {
+    fs2.mkdirSync(worktreePath, { recursive: true });
+    return { branch, worktree: path2.resolve(worktreePath), reused: false, fallback: "non_git" };
+  }
+  const startPoint = (() => {
+    try {
+      runGitFn(baseWorktree, ["rev-parse", "--verify", "dev"]);
+      return "dev";
+    } catch {
+      return "origin/dev";
+    }
+  })();
+  runGitFn(baseWorktree, ["worktree", "add", "-b", branch, worktreePath, startPoint]);
+  return { branch, worktree: path2.resolve(worktreePath), reused: false, startPoint };
+}
 function normalizeClickUpDefinitionDocParent(parent = {}) {
   const docId = String(parent.doc_id || parent.docId || CLICKUP_DEFINITION_DOC_PARENT.doc_id).trim();
   const pageId = String(parent.page_id || parent.pageId || CLICKUP_DEFINITION_DOC_PARENT.page_id).trim();
@@ -8571,6 +8628,7 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
       worktree,
       mirror_task_path: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
+      delivery_evidence_path: deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent),
       ...agentMetadata
     }
   });
@@ -8581,7 +8639,8 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     required_first_actions: [
       "Create or reuse the task-specific branch/worktree before planning or writing local .optima mirrors.",
       `Use branch ${branch} from dev and worktree ${worktree} for this task workspace.`,
-      "Write planning state, .optima/tasks/current.md, task mirrors, and evidence only inside the task worktree.",
+      "Write planning state, .optima/tasks/current.md, task mirrors, and local evidence only inside the task worktree.",
+      `Write merge-trackable final evidence under ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}; .optima remains local mirror/staging.`,
       "Do not update the principal dev workspace .optima/tasks/current.md for ClickUp task planning.",
       "If another active task is present in current.md, move to or create this task worktree instead of stopping."
     ],
@@ -8594,13 +8653,14 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     mirror: {
       taskPath: `.optima/tasks/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}.md`,
       evidenceSummaryPath: `.optima/evidences/${branchSafeClickUpId(taskId || subtaskId || effectiveParent)}/SUMMARY.md`,
+      deliveryEvidencePath: deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent),
       workspace: "task_worktree_only",
       principalWorkspaceCurrentMd: "do_not_update",
       currentMdConflictPolicy: "move_to_or_create_task_worktree",
       wouldCreate: true
     },
     clickup: {
-      comment: `Starting task from dev. Branch: ${branch}. Worktree: ${worktree}.`,
+      comment: `Starting task from dev. Branch: ${branch}. Worktree: ${worktree}. Delivery evidence: ${deliveryEvidencePathForClickUpTask(taskId || subtaskId || effectiveParent)}.`,
       description,
       fields: {
         Definition: definitionContent,
@@ -9391,6 +9451,11 @@ function clickUpPendingSessionKey(metadataKey) {
 function mergeClickUpPendingSessionMetadata(existing, metadataKey, sessionId) {
   return mergeClickUpSessionMetadata(existing, clickUpPendingSessionKey(metadataKey), sessionId);
 }
+function setClickUpTaskRoutingMetadata(existing, routing = {}) {
+  const root = normalizeAgentMetadataJson(existing);
+  root.task = { ...isPlainObject(root.task) ? root.task : {}, ...routing };
+  return JSON.stringify(sortJsonValue(root), null, 2);
+}
 function setClickUpSessionMetadata(existing, metadataKey, sessionId) {
   const root = normalizeAgentMetadataJson(existing);
   const parts = String(metadataKey || CLICKUP_PM_METADATA_KEY).split(".").filter(Boolean);
@@ -9485,16 +9550,20 @@ async function sendOpenCodeSessionEvent(client, { sessionId, agent, text, direct
   if (directBaseUrl) return sendOpenCodeSessionEventDirect({ baseUrl: directBaseUrl, sessionId, text, fetchImpl });
   throw new Error("OpenCode client does not expose session.prompt or session.promptAsync.");
 }
-function formatClickUpWebhookPrompt({ eventType, taskId, payload }) {
+function formatClickUpWebhookPrompt({ eventType, taskId, payload, branch = "", worktree = "", deliveryEvidencePath = "" }) {
   const comment = clickUpCommentFromPayload(payload);
   const commentText = clickUpCommentText(comment).trim();
   return [
     "[ClickUp Webhook Event]",
     `Event: ${eventType}`,
     `Task ID: ${taskId}`,
+    branch ? `Branch: ${branch}` : null,
+    worktree ? `Worktree: ${worktree}` : null,
+    deliveryEvidencePath ? `Delivery evidence path: ${deliveryEvidencePath}` : null,
     commentText ? `Comment: ${commentText}` : null,
     "",
-    "Handle this ClickUp Product Manager event using the ClickUp-first workflow rules. Do not assume broad chat routing; this event passed Optima webhook gates."
+    "Handle this ClickUp Product Manager event using the ClickUp-first workflow rules. Do not assume broad chat routing; this event passed Optima webhook gates.",
+    deliveryEvidencePath ? `Final merge-trackable evidence must be written under ${deliveryEvidencePath}; use .optima only as local mirror/staging.` : null
   ].filter((part) => part !== null).join("\n");
 }
 function appendClickUpWebhookLocalLog(worktree, entry) {
@@ -9673,7 +9742,7 @@ async function withClickUpTaskRouteLock(taskId, operation) {
     if (activeClickUpTaskRoutes.get(key) === current) activeClickUpTaskRoutes.delete(key);
   }
 }
-async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, saveState = null, now = () => /* @__PURE__ */ new Date(), host = os.hostname(), commentLedgerPath = clickUpCommentLedgerPath(worktree) } = {}) {
+async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, worktree = process.cwd(), clickupClient, openCodeClient, sessionExists = openCodeSessionExists, createSession = createOpenCodeSession, sendSessionEvent = sendOpenCodeSessionEvent, ensureTaskWorktree = ensureClickUpTaskWorktree, saveState = null, now = () => /* @__PURE__ */ new Date(), host = os.hostname(), commentLedgerPath = clickUpCommentLedgerPath(worktree) } = {}) {
   const eventType = clickUpEventType(payload);
   const eventKey = clickUpWebhookEventKey(payload);
   const remembered = rememberClickUpWebhookEvent(state, eventKey);
@@ -9721,11 +9790,31 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   const existingMetadata = clickUpTaskAgentMetadata(task, config.routing.metadataFieldId);
   const metadata = normalizeAgentMetadataJson(existingMetadata);
   const existingSessionId = getNestedMetadataValue(metadata, config.routing.metadataKey);
-  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload });
+  const taskType = clickUpTaskType(task);
+  const parentTaskId = clickUpParentTaskId(task) || taskId;
+  const subtaskId = parentTaskId && parentTaskId !== taskId ? taskId : "";
+  let taskRoute;
+  try {
+    taskRoute = ensureTaskWorktree({ baseWorktree: config.basePath, taskId, taskType, parentTaskId, subtaskId, existingMetadata: metadata, allowNonGitFallback: process.env.NODE_ENV === "test" });
+  } catch (error) {
+    const message = `Optima webhook could not create or reuse a task worktree for ${taskId}: ${error.message}`;
+    appendClickUpWebhookLocalLog(worktree, { type: "task_worktree_failed", taskId, message });
+    if (typeof clickupClient?.postTaskComment === "function") await clickupClient.postTaskComment({ taskId, comment: message });
+    return { ok: false, action: "error", reason: "task_worktree_failed", taskId, message };
+  }
+  const deliveryEvidencePath = deliveryEvidencePathForClickUpTask(taskId);
+  const routingMetadata = {
+    branch: taskRoute.branch,
+    worktree: taskRoute.worktree,
+    delivery_evidence_path: deliveryEvidencePath,
+    evidence_path: `.optima/evidences/${branchSafeClickUpId(taskId)}/SUMMARY.md`
+  };
+  const metadataWithRouting = setClickUpTaskRoutingMetadata(existingMetadata, routingMetadata);
+  const prompt = formatClickUpWebhookPrompt({ eventType, taskId, payload, branch: taskRoute.branch, worktree: taskRoute.worktree, deliveryEvidencePath });
   if (!existingSessionId) {
     let pendingSessionId = getNestedMetadataValue(metadata, clickUpPendingSessionKey(config.routing.metadataKey)) || state.pendingSessions?.[taskId];
     if (!pendingSessionId) {
-      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: config.basePath, agent: config.routing.targetAgent });
+      pendingSessionId = await createSession(openCodeClient, { title: sessionTitle, directory: taskRoute.worktree, agent: config.routing.targetAgent });
       if (!String(pendingSessionId || "").startsWith("ses_")) return { ok: false, action: "error", reason: "session_create_failed", taskId };
       if (saveState) {
         saveState({
@@ -9734,14 +9823,14 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
         });
       }
     }
-    const pendingMetadata = mergeClickUpPendingSessionMetadata(existingMetadata, config.routing.metadataKey, pendingSessionId);
+    const pendingMetadata = mergeClickUpPendingSessionMetadata(metadataWithRouting, config.routing.metadataKey, pendingSessionId);
     try {
       await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: pendingMetadata });
     } catch (error) {
       appendClickUpWebhookLocalLog(worktree, { type: "pending_session_metadata_failed", taskId, sessionId: pendingSessionId, message: error.message });
       throw error;
     }
-    await sendSessionEvent(openCodeClient, { sessionId: pendingSessionId, agent: config.routing.targetAgent, text: prompt, directory: config.basePath, opencodeBaseUrl: config.opencode?.baseUrl });
+    await sendSessionEvent(openCodeClient, { sessionId: pendingSessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl });
     const nextMetadata = clearClickUpPendingSessionMetadata(setClickUpSessionMetadata(pendingMetadata, config.routing.metadataKey, pendingSessionId), config.routing.metadataKey);
     await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: nextMetadata });
     const { [taskId]: _completedPending, ...remainingPending } = stateToPersist.pendingSessions || {};
@@ -9750,7 +9839,8 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
   }
   const sessionId = String(existingSessionId);
   if (await sessionExists(openCodeClient, sessionId)) {
-    await sendSessionEvent(openCodeClient, { sessionId, agent: config.routing.targetAgent, text: prompt, directory: config.basePath, opencodeBaseUrl: config.opencode?.baseUrl });
+    if (typeof clickupClient?.updateTaskMetadata === "function") await clickupClient.updateTaskMetadata({ taskId, fieldId: config.routing.metadataFieldId, value: metadataWithRouting });
+    await sendSessionEvent(openCodeClient, { sessionId, agent: config.routing.targetAgent, text: prompt, directory: taskRoute.worktree, opencodeBaseUrl: config.opencode?.baseUrl });
     return finish({ ok: true, action: "sent_to_existing_session", taskId, sessionId, eventKey });
   }
   const at = now().toISOString();
@@ -11522,7 +11612,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpCommentLedger, readClickUpWebhookState, recordClickUpCommentVersionProcessed, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, stableClickUpCommentVersionMarker, 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, BUNDLE_ASSETS_DIR, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentLedgerKey, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, deliveryEvidencePathForClickUpTask, ensureClickUpTaskWorktree, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpCommentLedger, readClickUpWebhookState, recordClickUpCommentVersionProcessed, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, stableClickUpCommentVersionMarker, 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.32",
+  "version": "0.1.34",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"