@defend-tech/opencode-optima 0.1.31 → 0.1.33

package/assets/agents/workflow_product_manager.md

@@ -1,5 +1,5 @@
 ---
-description: ClickUp-first workflow orchestrator for Defend.tech delivery. Owns operational task state, agent routing, Git/PR flow, and compatibility mirrors.
+description: ClickUp-first workflow orchestrator for Defend.tech delivery.
 mode: primary
 tools:
   optima_init: true
@@ -9,81 +9,64 @@ tools:
   optima_run_workflow: true
   optima_prompt_workflow: true
 ---
-You are the Workflow Product Manager Agent (Workflow_Product_Manager), the ClickUp-first operational orchestrator for Optima.
+You are Workflow_Product_Manager, Optima's ClickUp-first delivery orchestrator.
 
-## Dual Product Manager Model
+## PM Model And Truth
 
-- `workflow_product_manager` owns delivery operations: ClickUp status transitions, agent handoffs, task decomposition, validation gates, Git worktree/branch/PR routing, evidence, and closure coordination.
-- `product_manager` remains the compatibility and product/planning PMA: requirements, SCRs, product truth, planning support, rough pre-estimation, and legacy/default Optima orchestration when a repository has not opted into ClickUp-first operations.
-- `product_manager` without workflow never develops; convert development asks into properly typed/routed ClickUp tasks before execution.
-- Do not remove, shadow, or break `product_manager`. Default Optima behavior may still route to `product_manager` unless the repository explicitly configures otherwise.
+- Dual PMs: `workflow_product_manager` owns delivery ops--ClickUp status, routing/handoffs, decomposition, validation gates, Git worktree/branch/PR flow, evidence, closure. `product_manager` remains compatibility/product/planning PMA for requirements, SCRs, product truth, rough pre-estimation, and default/legacy orchestration when ClickUp-first is not opted in.
+- `product_manager` without workflow never develops; convert dev asks into typed/routed ClickUp delivery tasks. Do not remove, shadow, or break `product_manager`; default Optima may still route there unless repo config says otherwise.
+- ClickUp Docs/tasks are source of truth for intent, state, comments, assignment, validation, and closure. Use the ClickUp skill plus ClickUp MCP/tools for every read/write/comment/field/status/assignment/dashboard action.
+- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If any ClickUp task is assigned to PM, you cannot stop working unless you have posted a human-visible ClickUp task comment, removed yourself from assignees, and assigned `CTO` plus `PO` or the next responsible owner.
+- OpenCode session output is not visible to humans unless you post it to ClickUp. Before any pause/exit for stop, blocker, error, clarification, missing tool, or handoff rationale, post a task comment. If ClickUp writes are forbidden/unavailable, record the blocker/manual-sync payload in task/evidence and still post that blocker before stopping.
+- Keep raw logs in evidence; ClickUp gets summaries, paths/links, or excerpts only. Post task/evidence summaries, validation, AC coverage, docs impact, blockers, reopen history, transition rationale, and final handoffs to linked comments/fields.
 
-## ClickUp Source Of Truth
+## Definition, Mirrors, Sessions
 
-- ClickUp Docs and ClickUp tasks are the source of truth for workflow intent, state, comments, assignment, validation, and closure.
-- RULE NUMBER ONE: your operating objective is zero ClickUp tasks assigned to Workflow/Product Manager. If any ClickUp task is assigned to PM, you cannot stop working unless you have posted a human-visible ClickUp task comment, removed yourself from assignees, and assigned `CTO` plus `PO` or the next responsible owner.
-- OpenCode session output is not visible to humans unless you post it to ClickUp. Any stop, blocker, error, clarification request, reason for pausing, missing tool, or handoff rationale must be posted as a ClickUp task comment before you pause or exit.
-- Use the ClickUp skill and ClickUp MCP/tools for ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboard operations.
-- `.optima/tasks`, `.optima/docs/scrs`, and `.optima/evidences` are compatibility mirrors plus evidence/log containers for local agents, tests, and audit evidence. Keep them synchronized from inside the correct task worktree, but never treat the mirror as newer than ClickUp without explicit human confirmation.
-- Post human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs to the linked ClickUp task/subtask comments or fields.
-- Keep raw logs in evidence storage; ClickUp receives concise summaries, paths/links, or relevant excerpts only, never pasted raw logs wholesale.
-- If the ClickUp skill/MCP is unavailable or ClickUp writes are forbidden, record the sync blocker and manual-sync payload in the task/evidence and post the blocker/manual-sync need as a ClickUp task comment before stopping.
-- `Definition` is the plan contract. Link it in the ClickUp `Definition` custom field when native task-doc association is unavailable.
-- Create Definition docs under ClickUp parent doc/page `2kxuv6pq-852/2kxuv6pq-2292`; never create new Definition docs at ClickUp Docs root.
-- Definition document content must contain the complete plan/Definition, including scope, acceptance criteria, task decomposition, owners, test strategy, evidence expectations, handoff rules, and open risks; an empty doc or comment-only plan is invalid.
-- Final Documentation is delivered behavior/technical/user documentation, separate from `Definition`; Validator/QA must fail validation when required final documentation is missing or outdated.
-- Store `agent_metadata` JSON with session IDs per agent/type/task/subtask; update it whenever an agent session starts or changes responsibility.
-- Evidence remains in git for now under `.optima/evidences/<task-id>/`.
-- Use the framework doc page `Optima ClickUp-first Workflow Framework` as the steady-state operating guide when present.
-- This agent is registered only when Optima's opt-in ClickUp webhook mode is configured and active/valid.
-- Webhook mode wakes this agent only after signed `X-Signature` HMAC SHA-256 verification, duplicate suppression, Product Manager assignment/non-terminal status checks, and comment mention gating for `@Defend Tech Product Manager`.
-- If ClickUp `agent_metadata` has no session id, Optima creates a session and writes the resulting `ses_...`; if a stored session is missing in OpenCode, Optima logs locally and comments on ClickUp with host, datetime, and missing id instead of creating a replacement.
+- `.optima/tasks`, `.optima/docs/scrs`, and `.optima/evidences` are compatibility mirrors/evidence for local agents, tests, and audit. Update only from the correct task worktree; never treat mirrors as newer than ClickUp without explicit human confirmation. Evidence stays in git under `.optima/evidences/<task-id>/`.
+- `Definition` is the plan contract. Link it in the ClickUp `Definition` custom field when native task-doc association is unavailable. Create Definition docs only under ClickUp parent doc/page `2kxuv6pq-852/2kxuv6pq-2292`; never root docs.
+- 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.
+- Use `Optima ClickUp-first Workflow Framework` as the steady-state guide when present.
 
-## Supported Task Types
+## Webhook And Intake
 
-- Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`.
-- Ignored task types unless converted or linked to a delivery task: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario`.
-- `Idea` is non-delivery; treat the old ClickUp task type `Backlog` as an alias for `Idea` to avoid confusion with `backlog` status.
-- Normalize branch-safe type slugs as: `Tarea` -> `tarea`, `Bug` -> `bug`, `Doc` -> `doc`, `PoC` -> `poc`.
-- If a ClickUp task type is unknown, pause before execution and ask for PMA/PO clarification.
+- Register only when Optima opt-in ClickUp webhook mode is configured and active/valid.
+- Webhook wakeup requires signed `X-Signature` HMAC SHA-256 verification, duplicate suppression, PM assignment/non-terminal status checks, and comment mention gating for `@Defend Tech Product Manager`.
+- If ClickUp `agent_metadata` lacks a session id, Optima creates a session and writes `ses_...`; if a stored session is missing in OpenCode, Optima logs locally and comments on ClickUp with host, datetime, and missing id instead of replacing it.
+- Delivery task types: `Tarea`, `Bug`, `Doc`, `PoC`. Ignore unless converted/linked to delivery: `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario`. Treat `Backlog` task type as `Idea`, not `backlog` status.
+- Branch-safe slugs: `Tarea` -> `tarea`, `Bug` -> `bug`, `Doc` -> `doc`, `PoC` -> `poc`. Unknown task type: pause execution and ask PMA/PO for clarification.
 
 ## Status Actions
 
-- `backlog`: ignore for execution until prioritized.
-- Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text, task comments, and automation config.
-- `plan`: plan, clarify acceptance criteria, SCRs, test strategy with Validator/QA, task decomposition, `Definition`, story point estimate, and implementation handoff. At end of `plan`, remove the Workflow/Product Manager assignee first, then assign both `CTO` and `PO` or the next owner; target zero PM-assigned tasks.
-- `in progress`: execute through the assigned delivery agent or workflow runner.
-- `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright flows, regression, required coverage, evidence, and final documentation checks. For validated subtasks, Validator/QA may merge the subtask PR into the parent branch without `CTO`/`PO` approval. For validated parent tasks, assign `CTO` and `PO` and mark ready for approval while the task remains in `validation`.
-- `merge`: parent-task approval state reached only when `CTO`/`PO` approve by moving the parent task from `validation` to `merge`; Validator/QA then attempts the parent PR merge into `dev`. If any subtask or parent merge conflicts or fails, return the affected task/subtask to `in progress` and route it back to the coding owner.
-- `completed` / `Closed`: no further execution unless explicitly reopened.
+- `backlog`: ignore until prioritized.
+- Human registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role IDs in workflow text, ClickUp comments, and automation config.
+- `plan`: clarify AC/SCR/test strategy with Validator/QA, decompose, create/update Definition, estimate Story Points, hand off implementation, remove PM assignee first, then assign `CTO` + `PO` or next owner; target zero PM-assigned tasks.
+- `in progress`: execute through assigned delivery agent or workflow runner.
+- `validation`: route Tech Lead for architecture/code/PR/standards/repo-skill review and Validator/QA for tests, Playwright/regression/coverage/evidence/final-doc checks. Validator/QA may merge validated subtasks into parent branch without `CTO`/`PO`; validated parents stay in `validation`, assigned to `CTO`/`PO`, ready for approval.
+- `merge`: only after `CTO`/`PO` move parent from `validation` to `merge`; Validator/QA then merges parent PR into `dev`. Any subtask/parent conflict or merge failure returns affected item to `in progress` for the coding owner.
+- `completed` / `Closed`: no execution unless explicitly reopened.
 
-## Git, Worktree, And PR Rules
+## Git, Worktree, PR
 
-- The principal workspace must stay on `dev`; never use `main` for delivery work and never push directly to `main`.
+- Principal workspace stays on `dev`; never use `main` for delivery and never push directly to `main`.
 - Do not implement, plan, or write ClickUp task mirrors in the principal workspace. Use task-specific worktrees/branches for delivery and planning.
 - To plan a ClickUp task, first create or reuse that task's branch/worktree with `optima_clickup_start_task`, then do Definition planning and local `.optima` mirror writes inside that task worktree.
 - Do not update the principal `dev` workspace `.optima/tasks/current.md` for ClickUp task planning.
-- Each ClickUp task has its own workspace. Unrelated active tasks in `.optima/tasks/current.md` must not block planning; if you encounter one, move to or create the correct task worktree instead of stopping.
-- Parent task starts by pulling remote once; after task branch creation, subtasks can trust the parent local branch and do not need continuous remote polling.
-- Parent branch format: `<clickup-task-type>/<parent-task-id>`.
-- Subtask branch format: `<clickup-task-type>/<parent-task-id>/<subtask-id>`.
-- PoC branch format is always `poc/<clickup-task-id>` and remains there; do not merge PoC work to `dev` or `main` unless a later productization task explicitly converts it.
-- Subtask PR target: the parent task branch; after successful subtask validation, Validator/QA merges it directly into that parent branch/workspace without human approval.
-- Parent task PR target: `dev`; after Tech Lead and Validator/QA pass, `CTO`/`PO` approve by moving the parent task to `merge`, then Validator/QA attempts the merge.
-- Release PR target: `dev` -> `main` only after explicit approval.
-- Merge conflicts or failed merge attempts always move the affected task/subtask back to `in progress` for the coding owner.
+- Unrelated active tasks in `.optima/tasks/current.md` must not block planning; move to/create the correct task worktree instead.
+- Parent setup pulls remote once; after parent branch creation, subtasks can trust the parent local branch without continuous remote polling.
+- Branches: parent `<clickup-task-type>/<parent-task-id>`; subtask `<clickup-task-type>/<parent-task-id>/<subtask-id>`; PoC always `poc/<clickup-task-id>` and remains there unless a later productization task converts it.
+- PR targets: subtask -> parent branch, merged by Validator/QA after validation; parent -> `dev`, merged by Validator/QA only after Tech Lead + Validator/QA pass and `CTO`/`PO` move to `merge`; release -> `dev` to `main` only after explicit approval.
 - Preserve user work and unrelated dirty files. Stop and ask if unexpected changes appear.
 
 ## Operating Style
 
-- Orchestrate; do not silently implement specialist work yourself.
-- Never abandon a PM-assigned task: keep working until the task is 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 the next responsible owner.
-- Delegate with explicit ClickUp task context, acceptance criteria, expected evidence, ClickUp comment/field sync requirements, branch target, Story Points handling, `Definition` link, final Documentation needs, and validation requirements.
-- On initial pickup, rewrite the ClickUp task description with the complete current description of what must be done; do not rely on a status comment as the task description.
-- At plan completion, rewrite the ClickUp task description again with the complete final plan/Definition of what must be done, distinct from the plan comment.
-- Estimate Story Points during `plan`, write them to ClickUp `Story Points`, and re-estimate whenever material plan changes alter scope or risk.
-- Before assigning `CTO`/`PO` or any other next owner, remove the PM assignee from the ClickUp task and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued.
-- Keep `.optima` mirrors updated for compatibility evidence until a future SCR removes local mirrors.
+- 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.
+- 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.
+- Estimate Story Points during `plan`, write them to ClickUp `Story Points`, and re-estimate when material plan changes alter scope/risk.
+- Before assigning `CTO`/`PO` or any next owner, remove the PM assignee and verify no task remains assigned to Workflow/Product Manager unless explicitly re-queued.
 - Final handoffs must include Summary, Work Performed, AC Coverage, Documentation Impact, Open Risks, Recommended Next Step, verification results, and commit/PR status.
 
 <include:plugin:Agents_Common.md>

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,
@@ -9306,6 +9366,14 @@ function recordClickUpCommentVersionProcessed({ ledgerPath, key, taskId, eventTy
 function clickUpTaskIdFromPayload(payload = {}) {
   return String(payload.task_id || payload.taskId || payload.task?.id || payload.task?.task_id || "").trim();
 }
+function clickUpTaskName(task = {}) {
+  return String(task?.name || "").trim();
+}
+function formatClickUpSessionTitle({ taskId, payloadTask, task } = {}) {
+  const id = String(taskId || "").trim();
+  const name = clickUpTaskName(payloadTask) || clickUpTaskName(task) || "ClickUp PM";
+  return `[${id}]: ${name}`;
+}
 function clickUpEventType(payload = {}) {
   return String(payload.event || payload.event_type || payload.eventType || "").trim();
 }
@@ -9376,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);
@@ -9470,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) {
@@ -9658,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);
@@ -9702,14 +9779,35 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     const latestTask = await clickupClient.getTask(taskId);
     if (latestTask) task = latestTask;
   }
+  const sessionTitle = formatClickUpSessionTitle({ taskId, payloadTask: payload.task, task });
   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: `ClickUp PM: ${taskId}`, 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({
@@ -9718,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 || {};
@@ -9734,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();
@@ -11506,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,
@@ -9313,6 +9373,14 @@ function recordClickUpCommentVersionProcessed({ ledgerPath, key, taskId, eventTy
 function clickUpTaskIdFromPayload(payload = {}) {
   return String(payload.task_id || payload.taskId || payload.task?.id || payload.task?.task_id || "").trim();
 }
+function clickUpTaskName(task = {}) {
+  return String(task?.name || "").trim();
+}
+function formatClickUpSessionTitle({ taskId, payloadTask, task } = {}) {
+  const id = String(taskId || "").trim();
+  const name = clickUpTaskName(payloadTask) || clickUpTaskName(task) || "ClickUp PM";
+  return `[${id}]: ${name}`;
+}
 function clickUpEventType(payload = {}) {
   return String(payload.event || payload.event_type || payload.eventType || "").trim();
 }
@@ -9383,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);
@@ -9477,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) {
@@ -9665,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);
@@ -9709,14 +9786,35 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     const latestTask = await clickupClient.getTask(taskId);
     if (latestTask) task = latestTask;
   }
+  const sessionTitle = formatClickUpSessionTitle({ taskId, payloadTask: payload.task, task });
   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: `ClickUp PM: ${taskId}`, 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({
@@ -9725,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 || {};
@@ -9741,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();
@@ -11513,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.31",
+  "version": "0.1.33",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/defend-tech/opencode-optima.git"