@defend-tech/opencode-optima 0.1.23 → 0.1.25

package/Agents_Common.md

@@ -12,12 +12,13 @@
 - Use the ClickUp skill and ClickUp MCP/tools for all ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboard operations; if unavailable or forbidden, state the sync blocker and leave a manual-sync payload in task/evidence.
 - Before writing ClickUp updates from local artifacts, use Optima Markdown-driven sync tools (`optima_clickup_start_task`, `optima_clickup_sync_summary`, `optima_clickup_transition`, `optima_clickup_create_subtasks`, `optima_clickup_apply_payload`) to derive payloads from `.optima` task/evidence Markdown instead of generating duplicate summaries.
 - Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs are the right source and must be posted to the linked ClickUp task/subtask comments or fields; subtasks come from strict plan/Definition `## Subtasks` sections via `optima_clickup_create_subtasks`.
+- WPM rewrites the ClickUp task description on initial pickup and again at plan completion with the complete current/final description of what must be done, distinct from comments.
 - Keep raw logs in evidence storage; do not paste raw logs wholesale into ClickUp. Post concise summaries, paths/links, or relevant excerpts only.
 - `product_manager` may investigate, answer, pre-estimate "a qué huele" small/medium/large plus rough story points, and operate ClickUp dashboards; development requests must be converted into properly routed ClickUp tasks.
 - ClickUp delivery types are `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, and `Respuesta del formulario` unless converted or linked.
 - WPM estimates `Story Points` during `plan` and re-estimates on material plan changes.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and code instead of personal names.
-- ClickUp status actions: `backlog` ignore, `plan` plan plus assign `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. After validation, Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
+- ClickUp status actions: `backlog` ignore, `plan` plan plus remove the PM assignee before assigning `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. After validation, Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
 - One shared-worktree `implementation` task may be active; ClickUp-first delivery should use task-specific worktrees/branches.
 - Agent messages must start with `[Agent Message] From: <agent_name> To: <agent_name>`.
 - Clarifications, blockers, dependencies, and reviews go through PMA.
@@ -26,7 +27,7 @@
 - No task is done with failing builds/tests, skipped tests, missing validation, or incomplete documentation closure.
 - Final reports must trace numbered acceptance criteria to verification results.
 - After implementation, update the task file with `# Post Implementation Task Updates` and `## <Agent Name>: Post Implementation Expectations`.
-- `Definition` is the plan contract and may be linked in ClickUp field `Definition`; final Documentation is delivered behavior documentation and is separately required when relevant.
+- `Definition` is the plan contract and may be linked in ClickUp field `Definition`; Definition docs default under ClickUp parent doc/page `2kxuv6pq-852/2kxuv6pq-2292` and must contain the complete plan/Definition content, not an empty page or comment-only plan; final Documentation is delivered behavior documentation and is separately required when relevant.
 - ClickUp webhook mode validates `X-Signature` HMAC SHA-256, deduplicates events, ignores self-authored comments, routes only PM-assigned non-terminal tasks, wakes comments only on `@Defend Tech Product Manager`, writes new Product Manager `ses_...` ids to `agent_metadata`, and reports missing stored sessions with host/datetime/id instead of creating replacements.
 - Documentation closure is mandatory: update product/architecture/technical docs when relevant or explicitly state no product-doc update is required; Validator/QA fails validation when required final documentation is missing or stale.
 - Reopen same-scope discrepancies in the original task file with `Reopen History`; reuse Task/Workflow Runner session IDs when possible.

package/Agents_Common.prompt.md

@@ -14,12 +14,13 @@
 - Use the ClickUp skill and ClickUp MCP/tools for all ClickUp reads, writes, comments, field updates, status transitions, assignments, and dashboard operations; if unavailable or forbidden, state the sync blocker and leave a manual-sync payload in task/evidence.
 - Before writing ClickUp updates from local artifacts, use Optima Markdown-driven sync tools (`optima_clickup_start_task`, `optima_clickup_sync_summary`, `optima_clickup_transition`, `optima_clickup_create_subtasks`, `optima_clickup_apply_payload`) to derive payloads from `.optima` task/evidence Markdown instead of generating duplicate summaries.
 - Human-readable task/evidence summaries, validation results, AC coverage, documentation impact, blockers, reopen history, status-transition rationale, and final handoffs are the right source and must be posted to the linked ClickUp task/subtask comments or fields; subtasks come from strict plan/Definition `## Subtasks` sections via `optima_clickup_create_subtasks`.
+- WPM rewrites the ClickUp task description on initial pickup and again at plan completion with the complete current/final description of what must be done, distinct from comments.
 - Keep raw logs in evidence storage; do not paste raw logs wholesale into ClickUp. Post concise summaries, paths/links, or relevant excerpts only.
 - `product_manager` may investigate, answer, pre-estimate "a qué huele" small/medium/large plus rough story points, and operate ClickUp dashboards; development requests must become routed ClickUp tasks.
 - ClickUp-first delivery types: `Tarea`, `Bug`, `Doc`, `PoC`; ignore `Idea`, legacy `Backlog` alias, `Hito`, `Nota de reunión`, `Respuesta del formulario` unless converted or linked.
 - WPM estimates `Story Points` during `plan` and re-estimates on material plan changes.
 - Human role registry: resolve `CTO` and `PO` from `docs/core/humans.md`; use role identifiers in workflow text and code instead of personal names.
-- ClickUp-first statuses: `backlog` ignore, `plan` plan plus assign `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
+- ClickUp-first statuses: `backlog` ignore, `plan` plan plus remove the PM assignee before assigning `CTO`/`PO` at plan end, `in progress` execute, `validation` Tech Lead + Validator/QA gates. Validator/QA may merge validated subtasks into the parent branch without `CTO`/`PO` approval; validated parent tasks stay in `validation` for `CTO`/`PO` approval, they approve by moving the parent to `merge`, and Validator/QA then attempts the parent merge into `dev`. `completed`/`Closed` ignore unless reopened.
 - Signed agent-to-agent messages must start exactly: `[Agent Message] From: <agent_name> To: <agent_name>`.
 - Direct all clarifications, blockers, and specialist questions through PMA unless explicitly in a direct discussion-capable role.
 - Read relevant docs/tasks fully when they govern the current work. Prefer targeted CodeMap navigation before broad source search.
@@ -27,7 +28,7 @@
 - No task is done with failing builds, failing tests, skipped tests, or missing validation. Fix failures instead of accepting them.
 - Final evidence must trace numbered acceptance criteria (`AC-1`, `AC-2`, ...) to verification results.
 - After implementation, update the task file with `# Post Implementation Task Updates` and `## <Agent Name>: Post Implementation Expectations`.
-- `Definition` is the plan contract and may be linked in ClickUp field `Definition`; final Documentation is delivered behavior documentation and separately required when relevant.
+- `Definition` is the plan contract and may be linked in ClickUp field `Definition`; Definition docs default under ClickUp parent doc/page `2kxuv6pq-852/2kxuv6pq-2292` and must contain the complete plan/Definition content, not an empty page or comment-only plan; final Documentation is delivered behavior documentation and separately required when relevant.
 - ClickUp webhook mode validates `X-Signature` HMAC SHA-256, deduplicates events, ignores self-authored comments, routes only PM-assigned non-terminal tasks, wakes comments only on `@Defend Tech Product Manager`, writes new Product Manager `ses_...` ids to `agent_metadata`, and reports missing stored sessions with host/datetime/id instead of creating replacements.
 - Documentation closure is mandatory: update product/architecture/technical docs when relevant or explicitly state that product documentation is not required; Validator/QA fails validation when required final documentation is missing or stale.
 - Reopen/resume same-scope fixes in the original task file. Record `Reopen History`; reuse Task tool `task_id` and Workflow Runner `session_id` when possible.

package/agents/codemap.yml

@@ -9,3 +9,6 @@ sources_of_truth:
   - path: developer.md
   - path: qa_engineer.md
   - path: ui_ux_designer.md
+internals:
+  - path: ops_product_manager.md
+  - path: workflow_product_manager.md

package/agents/workflow_product_manager.md

@@ -27,6 +27,8 @@ You are the Workflow Product Manager Agent (Workflow_Product_Manager), the Click
 - 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.
 - `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>/`.
@@ -47,7 +49,7 @@ You are the Workflow Product Manager Agent (Workflow_Product_Manager), the Click
 
 - `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`, assign both `CTO` and `PO`.
+- `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.
@@ -71,7 +73,10 @@ You are the Workflow Product Manager Agent (Workflow_Product_Manager), the Click
 
 - Orchestrate; do not silently implement specialist work yourself.
 - 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.
 - Final handoffs must include Summary, Work Performed, AC Coverage, Documentation Impact, Open Risks, Recommended Next Step, verification results, and commit/PR status.
 

package/dist/index.js

@@ -7908,6 +7908,11 @@ var MANDATORY_AGENTS = /* @__PURE__ */ new Set(["product_manager", "business_ana
 var MINI_MODE_AGENTS = /* @__PURE__ */ new Set(["product_manager", "business_analyst", "tech_lead"]);
 var CLICKUP_IGNORED_TASK_TYPES = ["Idea", "Backlog", "Hito", "Nota de reuni\xF3n", "Respuesta del formulario"];
 var CLICKUP_FINAL_APPROVER_ROLES = ["CTO", "PO"];
+var CLICKUP_PM_ASSIGNEE_PLACEHOLDER = "product_manager";
+var CLICKUP_DEFINITION_DOC_PARENT = {
+  doc_id: "2kxuv6pq-852",
+  page_id: "2kxuv6pq-2292"
+};
 var CLICKUP_STORY_POINT_ESTIMATES = {
   small: 2,
   medium: 5,
@@ -8528,7 +8533,25 @@ function deriveClickUpWorktree({ baseWorktree = "", taskId, taskType, parentTask
   const root = baseWorktree || process.cwd();
   return path2.join(path2.dirname(root), `${path2.basename(root)}-${branch.replace(/\//g, "-")}`);
 }
-function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", baseWorktree = "", definition = "", complexity = "standard", filesChanged = 0, acceptanceCriteria = 0, unknowns = 0, existingAgentMetadata = "", agentMetadata = {}, apply = false } = {}) {
+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();
+  return { doc_id: docId, page_id: pageId };
+}
+function isRealClickUpAssigneeId(value) {
+  const id = String(value || "").trim();
+  return Boolean(id) && id !== CLICKUP_PM_ASSIGNEE_PLACEHOLDER;
+}
+function clickUpPayloadValidationError(errors = []) {
+  return { ok: false, mode: "payload", dryRun: true, errors };
+}
+function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", baseWorktree = "", definition = "", taskDescription = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, complexity = "standard", filesChanged = 0, acceptanceCriteria = 0, unknowns = 0, existingAgentMetadata = "", agentMetadata = {}, apply = false } = {}) {
+  const definitionContent = compactMarkdownValue(definition);
+  const description = compactMarkdownValue(taskDescription);
+  const errors = [];
+  if (!definitionContent) errors.push("definition is required and must contain the complete plan/Definition content.");
+  if (!description) errors.push("taskDescription is required for the initial ClickUp task description rewrite.");
+  if (errors.length > 0) return clickUpPayloadValidationError(errors);
   const effectiveParent = parentTaskId || taskId;
   const branch = deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
   const worktree = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
@@ -8559,17 +8582,23 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     },
     clickup: {
       comment: `Starting task from dev. Branch: ${branch}. Worktree: ${worktree}.`,
+      description,
       fields: {
-        Definition: definition,
+        Definition: definitionContent,
         "Story Points": estimate.storyPoints,
         agent_metadata: metadata,
         branch,
         worktree
+      },
+      definition_doc: {
+        parent: normalizeClickUpDefinitionDocParent(definitionDocParent),
+        content: definitionContent,
+        required: true
       }
     }
   };
 }
-function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], humansRegistry } = {}) {
+function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], removeAssignees = [], productManagerAssignee = "", requireProductManagerAssignee = true, planDescription = "", definition = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, humansRegistry } = {}) {
   const from = normalizeClickUpStatus(fromStatus);
   let to = normalizeClickUpStatus(toStatus);
   if (validationFailed) to = "in progress";
@@ -8580,9 +8609,27 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
   const key = `${from}->${to}`;
   const rule = CLICKUP_TRANSITIONS.get(key);
   if (!rule) return { ok: false, dryRun: true, message: `Transition not allowed: ${key}` };
+  const assignsFinalApprovers = rule.assignFinalApprovers === true;
+  const requiresPlanCompletionContract = from === "plan" && assignsFinalApprovers;
+  const definitionContent = compactMarkdownValue(definition);
+  const description = compactMarkdownValue(planDescription);
+  const validationErrors = [];
+  if (assignsFinalApprovers && !isRealClickUpAssigneeId(productManagerAssignee) && requireProductManagerAssignee !== false) {
+    validationErrors.push("productManagerAssignee must be the configured ClickUp PM assignee ID before assigning final approvers.");
+  }
+  if (requiresPlanCompletionContract) {
+    if (!description) validationErrors.push("planDescription is required for the plan-completion ClickUp task description rewrite.");
+    if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
+  }
+  if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
   const finalApprovers = rule.assignFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
-  const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))];
+  const explicitRemovals = (removeAssignees || []).filter(Boolean);
+  const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
+  const removalTargets = rule.assignFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
+  const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))].filter((assignee) => !removalTargets.includes(assignee));
   const authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
+  const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
+  if (definitionContent) fields.Definition = definitionContent;
   return {
     ok: true,
     dryRun: true,
@@ -8590,8 +8637,19 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     clickup: {
       status: rule.status,
       assignees: assigned,
+      assignment_delta: {
+        add: assigned,
+        remove: removalTargets,
+        objective: rule.assignFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
+      },
       comment: rule.comment,
-      fields: authority ? { merge_authority: JSON.stringify(authority) } : {}
+      description,
+      fields,
+      definition_doc: definitionContent ? {
+        parent: normalizeClickUpDefinitionDocParent(definitionDocParent),
+        content: definitionContent,
+        required: true
+      } : void 0
     }
   };
 }
@@ -9177,12 +9235,15 @@ function clickUpCommentAuthorId(comment = {}) {
   return String(comment.user?.id || comment.user?.userid || comment.author?.id || comment.author_id || comment.user_id || "").trim();
 }
 function clickUpCommentText(comment = {}) {
-  return String(comment.comment_text || comment.text || comment.comment || comment.plain_text || "");
+  if (Array.isArray(comment.comment)) return comment.comment.map((part) => String(part?.text || "")).join("");
+  return String(comment.comment_text || comment.text || comment.comment || comment.plain_text || comment.text_content || "");
 }
 function clickUpCommentMentionsProductManager(comment = {}, routing = {}) {
   const mentionUserId = String(routing.productManagerMentionUserId || "").trim();
   const mentions = Array.isArray(comment.mentions) ? comment.mentions : [];
   if (mentionUserId && mentions.some((mention) => String(mention?.id || mention?.userid || mention?.user?.id || mention).trim() === mentionUserId)) return true;
+  const richText = Array.isArray(comment.comment) ? comment.comment : [];
+  if (mentionUserId && richText.some((part) => part?.type === "tag" && String(part?.user?.id || part?.user?.userid || "").trim() === mentionUserId)) return true;
   const fallback = String(routing.productManagerMentionName || CLICKUP_PM_MENTION_NAME).trim().toLowerCase();
   return fallback ? clickUpCommentText(comment).toLowerCase().includes(`@${fallback}`) : false;
 }
@@ -9526,7 +9587,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     if (authorId && authorId === config.routing.ignoredCommentAuthorId) return finish({ ok: true, action: "ignored", reason: "self_authored_comment", taskId });
     if (!clickUpCommentMentionsProductManager(comment, config.routing)) return finish({ ok: true, action: "ignored", reason: "missing_product_manager_mention", taskId });
   }
-  if (!isClickUpTaskAssignedToProductManager(task, config.routing.productManagerAssigneeId)) return finish({ ok: true, action: "ignored", reason: "not_assigned_to_product_manager", taskId });
+  if (!isCommentEvent && !isClickUpTaskAssignedToProductManager(task, config.routing.productManagerAssigneeId)) return finish({ ok: true, action: "ignored", reason: "not_assigned_to_product_manager", taskId });
   if (isClickUpTaskTerminal(task, payload, config.routing.ignoredStatuses)) return finish({ ok: true, action: "ignored", reason: "terminal_status", taskId });
   if (clickupClient?.getTask) {
     const latestTask = await clickupClient.getTask(taskId);
@@ -10902,7 +10963,8 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         task_type: tool.schema.string().describe("ClickUp task type: Tarea, Bug, Doc, or PoC"),
         parent_task_id: tool.schema.string().describe("Optional parent ClickUp task ID"),
         subtask_id: tool.schema.string().describe("Optional subtask ID"),
-        definition: tool.schema.string().describe("Plan/Definition field content"),
+        definition: tool.schema.string().describe("Complete plan/Definition field and Definition doc content"),
+        task_description: tool.schema.string().describe("Complete ClickUp task description to rewrite on pickup; defaults to definition"),
         complexity: tool.schema.string().describe("tiny, standard, or complex"),
         apply: tool.schema.string().describe("Set to 'true' only to mark an apply request; this implementation still returns a dry-run payload only")
       },
@@ -10916,6 +10978,8 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
           subtaskId: args.subtask_id,
           baseWorktree: safe.worktree,
           definition: args.definition,
+          taskDescription: args.task_description,
+          definitionDocParent: repoCfg.workflow?.clickup?.definition_doc_parent,
           complexity: args.complexity || "standard",
           apply: String(args.apply || "").toLowerCase() === "true"
         });
@@ -10930,7 +10994,10 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         validation_passed: tool.schema.string().describe("Set to 'true' when validation passed"),
         validation_failed: tool.schema.string().describe("Set to 'true' when validation failed"),
         is_subtask: tool.schema.string().describe("Set to 'true' for subtask transitions"),
-        reopen: tool.schema.string().describe("Set to 'true' to reopen completed/closed tasks")
+        reopen: tool.schema.string().describe("Set to 'true' to reopen completed/closed tasks"),
+        product_manager_assignee: tool.schema.string().describe("Current Product Manager assignee ID to remove when assigning final approvers"),
+        plan_description: tool.schema.string().describe("Complete ClickUp task description to rewrite at plan completion"),
+        definition: tool.schema.string().describe("Complete plan/Definition content for the ClickUp Definition field/doc")
       },
       async execute(args) {
         const payload = buildClickUpTransitionPayload({
@@ -10939,7 +11006,11 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
           validationPassed: String(args.validation_passed || "").toLowerCase() === "true",
           validationFailed: String(args.validation_failed || "").toLowerCase() === "true",
           isSubtask: String(args.is_subtask || "").toLowerCase() === "true",
-          reopen: String(args.reopen || "").toLowerCase() === "true"
+          reopen: String(args.reopen || "").toLowerCase() === "true",
+          productManagerAssignee: args.product_manager_assignee || clickUpWebhookValidation.config?.routing?.productManagerAssigneeId || "",
+          planDescription: args.plan_description,
+          definition: args.definition,
+          definitionDocParent: repoCfg.workflow?.clickup?.definition_doc_parent
         });
         return JSON.stringify(payload, null, 2);
       }
@@ -11326,7 +11397,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, 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, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, 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

@@ -7915,6 +7915,11 @@ var MANDATORY_AGENTS = /* @__PURE__ */ new Set(["product_manager", "business_ana
 var MINI_MODE_AGENTS = /* @__PURE__ */ new Set(["product_manager", "business_analyst", "tech_lead"]);
 var CLICKUP_IGNORED_TASK_TYPES = ["Idea", "Backlog", "Hito", "Nota de reuni\xF3n", "Respuesta del formulario"];
 var CLICKUP_FINAL_APPROVER_ROLES = ["CTO", "PO"];
+var CLICKUP_PM_ASSIGNEE_PLACEHOLDER = "product_manager";
+var CLICKUP_DEFINITION_DOC_PARENT = {
+  doc_id: "2kxuv6pq-852",
+  page_id: "2kxuv6pq-2292"
+};
 var CLICKUP_STORY_POINT_ESTIMATES = {
   small: 2,
   medium: 5,
@@ -8535,7 +8540,25 @@ function deriveClickUpWorktree({ baseWorktree = "", taskId, taskType, parentTask
   const root = baseWorktree || process.cwd();
   return path2.join(path2.dirname(root), `${path2.basename(root)}-${branch.replace(/\//g, "-")}`);
 }
-function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", baseWorktree = "", definition = "", complexity = "standard", filesChanged = 0, acceptanceCriteria = 0, unknowns = 0, existingAgentMetadata = "", agentMetadata = {}, apply = false } = {}) {
+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();
+  return { doc_id: docId, page_id: pageId };
+}
+function isRealClickUpAssigneeId(value) {
+  const id = String(value || "").trim();
+  return Boolean(id) && id !== CLICKUP_PM_ASSIGNEE_PLACEHOLDER;
+}
+function clickUpPayloadValidationError(errors = []) {
+  return { ok: false, mode: "payload", dryRun: true, errors };
+}
+function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId = "", subtaskId = "", baseWorktree = "", definition = "", taskDescription = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, complexity = "standard", filesChanged = 0, acceptanceCriteria = 0, unknowns = 0, existingAgentMetadata = "", agentMetadata = {}, apply = false } = {}) {
+  const definitionContent = compactMarkdownValue(definition);
+  const description = compactMarkdownValue(taskDescription);
+  const errors = [];
+  if (!definitionContent) errors.push("definition is required and must contain the complete plan/Definition content.");
+  if (!description) errors.push("taskDescription is required for the initial ClickUp task description rewrite.");
+  if (errors.length > 0) return clickUpPayloadValidationError(errors);
   const effectiveParent = parentTaskId || taskId;
   const branch = deriveClickUpBranchName({ taskType, parentTaskId: effectiveParent, subtaskId, taskId });
   const worktree = deriveClickUpWorktree({ baseWorktree, taskId, taskType, parentTaskId: effectiveParent, subtaskId });
@@ -8566,17 +8589,23 @@ function buildClickUpStartTaskPayload({ taskId, taskType = "Tarea", parentTaskId
     },
     clickup: {
       comment: `Starting task from dev. Branch: ${branch}. Worktree: ${worktree}.`,
+      description,
       fields: {
-        Definition: definition,
+        Definition: definitionContent,
         "Story Points": estimate.storyPoints,
         agent_metadata: metadata,
         branch,
         worktree
+      },
+      definition_doc: {
+        parent: normalizeClickUpDefinitionDocParent(definitionDocParent),
+        content: definitionContent,
+        required: true
       }
     }
   };
 }
-function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], humansRegistry } = {}) {
+function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed = false, validationFailed = false, isSubtask = false, reopen = false, assignees = [], removeAssignees = [], productManagerAssignee = "", requireProductManagerAssignee = true, planDescription = "", definition = "", definitionDocParent = CLICKUP_DEFINITION_DOC_PARENT, humansRegistry } = {}) {
   const from = normalizeClickUpStatus(fromStatus);
   let to = normalizeClickUpStatus(toStatus);
   if (validationFailed) to = "in progress";
@@ -8587,9 +8616,27 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
   const key = `${from}->${to}`;
   const rule = CLICKUP_TRANSITIONS.get(key);
   if (!rule) return { ok: false, dryRun: true, message: `Transition not allowed: ${key}` };
+  const assignsFinalApprovers = rule.assignFinalApprovers === true;
+  const requiresPlanCompletionContract = from === "plan" && assignsFinalApprovers;
+  const definitionContent = compactMarkdownValue(definition);
+  const description = compactMarkdownValue(planDescription);
+  const validationErrors = [];
+  if (assignsFinalApprovers && !isRealClickUpAssigneeId(productManagerAssignee) && requireProductManagerAssignee !== false) {
+    validationErrors.push("productManagerAssignee must be the configured ClickUp PM assignee ID before assigning final approvers.");
+  }
+  if (requiresPlanCompletionContract) {
+    if (!description) validationErrors.push("planDescription is required for the plan-completion ClickUp task description rewrite.");
+    if (!definitionContent) validationErrors.push("definition is required and must contain the complete plan/Definition content at plan completion.");
+  }
+  if (validationErrors.length > 0) return clickUpPayloadValidationError(validationErrors);
   const finalApprovers = rule.assignFinalApprovers ? finalApprovalAssignees(CLICKUP_FINAL_APPROVER_ROLES, humansRegistry) : [];
-  const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))];
+  const explicitRemovals = (removeAssignees || []).filter(Boolean);
+  const normalizedProductManagerAssignee = isRealClickUpAssigneeId(productManagerAssignee) ? String(productManagerAssignee).trim() : "";
+  const removalTargets = rule.assignFinalApprovers ? [...new Set([normalizedProductManagerAssignee, ...explicitRemovals].filter(Boolean))] : explicitRemovals;
+  const assigned = [...new Set([...assignees || [], ...finalApprovers].filter(Boolean))].filter((assignee) => !removalTargets.includes(assignee));
   const authority = from === "validation" || to === "merge" ? determineClickUpMergeAuthority({ isSubtask, clickupStatus: to, validationPassed: validationPassed || to === "merge", humansRegistry }) : null;
+  const fields = authority ? { merge_authority: JSON.stringify(authority) } : {};
+  if (definitionContent) fields.Definition = definitionContent;
   return {
     ok: true,
     dryRun: true,
@@ -8597,8 +8644,19 @@ function buildClickUpTransitionPayload({ fromStatus, toStatus, validationPassed
     clickup: {
       status: rule.status,
       assignees: assigned,
+      assignment_delta: {
+        add: assigned,
+        remove: removalTargets,
+        objective: rule.assignFinalApprovers ? "zero_product_manager_assigned_tasks" : "preserve_existing_owner_policy"
+      },
       comment: rule.comment,
-      fields: authority ? { merge_authority: JSON.stringify(authority) } : {}
+      description,
+      fields,
+      definition_doc: definitionContent ? {
+        parent: normalizeClickUpDefinitionDocParent(definitionDocParent),
+        content: definitionContent,
+        required: true
+      } : void 0
     }
   };
 }
@@ -9184,12 +9242,15 @@ function clickUpCommentAuthorId(comment = {}) {
   return String(comment.user?.id || comment.user?.userid || comment.author?.id || comment.author_id || comment.user_id || "").trim();
 }
 function clickUpCommentText(comment = {}) {
-  return String(comment.comment_text || comment.text || comment.comment || comment.plain_text || "");
+  if (Array.isArray(comment.comment)) return comment.comment.map((part) => String(part?.text || "")).join("");
+  return String(comment.comment_text || comment.text || comment.comment || comment.plain_text || comment.text_content || "");
 }
 function clickUpCommentMentionsProductManager(comment = {}, routing = {}) {
   const mentionUserId = String(routing.productManagerMentionUserId || "").trim();
   const mentions = Array.isArray(comment.mentions) ? comment.mentions : [];
   if (mentionUserId && mentions.some((mention) => String(mention?.id || mention?.userid || mention?.user?.id || mention).trim() === mentionUserId)) return true;
+  const richText = Array.isArray(comment.comment) ? comment.comment : [];
+  if (mentionUserId && richText.some((part) => part?.type === "tag" && String(part?.user?.id || part?.user?.userid || "").trim() === mentionUserId)) return true;
   const fallback = String(routing.productManagerMentionName || CLICKUP_PM_MENTION_NAME).trim().toLowerCase();
   return fallback ? clickUpCommentText(comment).toLowerCase().includes(`@${fallback}`) : false;
 }
@@ -9533,7 +9594,7 @@ async function routeClickUpWebhookEventUnlocked({ payload, config, state = {}, w
     if (authorId && authorId === config.routing.ignoredCommentAuthorId) return finish({ ok: true, action: "ignored", reason: "self_authored_comment", taskId });
     if (!clickUpCommentMentionsProductManager(comment, config.routing)) return finish({ ok: true, action: "ignored", reason: "missing_product_manager_mention", taskId });
   }
-  if (!isClickUpTaskAssignedToProductManager(task, config.routing.productManagerAssigneeId)) return finish({ ok: true, action: "ignored", reason: "not_assigned_to_product_manager", taskId });
+  if (!isCommentEvent && !isClickUpTaskAssignedToProductManager(task, config.routing.productManagerAssigneeId)) return finish({ ok: true, action: "ignored", reason: "not_assigned_to_product_manager", taskId });
   if (isClickUpTaskTerminal(task, payload, config.routing.ignoredStatuses)) return finish({ ok: true, action: "ignored", reason: "terminal_status", taskId });
   if (clickupClient?.getTask) {
     const latestTask = await clickupClient.getTask(taskId);
@@ -10909,7 +10970,8 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         task_type: tool.schema.string().describe("ClickUp task type: Tarea, Bug, Doc, or PoC"),
         parent_task_id: tool.schema.string().describe("Optional parent ClickUp task ID"),
         subtask_id: tool.schema.string().describe("Optional subtask ID"),
-        definition: tool.schema.string().describe("Plan/Definition field content"),
+        definition: tool.schema.string().describe("Complete plan/Definition field and Definition doc content"),
+        task_description: tool.schema.string().describe("Complete ClickUp task description to rewrite on pickup; defaults to definition"),
         complexity: tool.schema.string().describe("tiny, standard, or complex"),
         apply: tool.schema.string().describe("Set to 'true' only to mark an apply request; this implementation still returns a dry-run payload only")
       },
@@ -10923,6 +10985,8 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
           subtaskId: args.subtask_id,
           baseWorktree: safe.worktree,
           definition: args.definition,
+          taskDescription: args.task_description,
+          definitionDocParent: repoCfg.workflow?.clickup?.definition_doc_parent,
           complexity: args.complexity || "standard",
           apply: String(args.apply || "").toLowerCase() === "true"
         });
@@ -10937,7 +11001,10 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
         validation_passed: tool.schema.string().describe("Set to 'true' when validation passed"),
         validation_failed: tool.schema.string().describe("Set to 'true' when validation failed"),
         is_subtask: tool.schema.string().describe("Set to 'true' for subtask transitions"),
-        reopen: tool.schema.string().describe("Set to 'true' to reopen completed/closed tasks")
+        reopen: tool.schema.string().describe("Set to 'true' to reopen completed/closed tasks"),
+        product_manager_assignee: tool.schema.string().describe("Current Product Manager assignee ID to remove when assigning final approvers"),
+        plan_description: tool.schema.string().describe("Complete ClickUp task description to rewrite at plan completion"),
+        definition: tool.schema.string().describe("Complete plan/Definition content for the ClickUp Definition field/doc")
       },
       async execute(args) {
         const payload = buildClickUpTransitionPayload({
@@ -10946,7 +11013,11 @@ Restart or reload OpenCode manually if the newly scaffolded config or agents are
           validationPassed: String(args.validation_passed || "").toLowerCase() === "true",
           validationFailed: String(args.validation_failed || "").toLowerCase() === "true",
           isSubtask: String(args.is_subtask || "").toLowerCase() === "true",
-          reopen: String(args.reopen || "").toLowerCase() === "true"
+          reopen: String(args.reopen || "").toLowerCase() === "true",
+          productManagerAssignee: args.product_manager_assignee || clickUpWebhookValidation.config?.routing?.productManagerAssigneeId || "",
+          planDescription: args.plan_description,
+          definition: args.definition,
+          definitionDocParent: repoCfg.workflow?.clickup?.definition_doc_parent
         });
         return JSON.stringify(payload, null, 2);
       }
@@ -11333,7 +11404,7 @@ Follow-up: use optima_prompt_workflow with session_id '${sessionId}' to check in
     }
   };
 }
-OptimaPlugin.__internals = { BUNDLE_AGENTS_DIR, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, 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, CLICKUP_DEFINITION_DOC_PARENT, activeClickUpWebhookLifecycleRegistry, cleanupManagedClickUpWebhook, deleteClickUpWebhookBestEffort, BUNDLE_POLICIES_DIR, buildClickUpApplyPayloadResult, buildClickUpCreateSubtasksPayload, buildClickUpStartTaskPayload, buildClickUpSummaryPayload, buildClickUpTransitionPayload, buildOptimaAgents, clickUpCommentMentionsProductManager, clickUpWebhookAuditLogDir, clickUpWebhookAuditLogPath, createClickUpApiClient, ensureClickUpWebhookSubscription, handleClickUpWebhookRequest, isClickUpWebhookStateActive, normalizeClickUpWebhookConfig, normalizeClickUpWebhookLogLevel, normalizeOpenCodeBaseUrl, readClickUpWebhookState, resolveOptimaPluginOptions, resolveSecretReference, routeClickUpWebhookEvent, sendOpenCodeSessionEvent, sendOpenCodeSessionEventDirect, 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/docs/core/codemap.yml

@@ -25,3 +25,4 @@ internals:
   - path: documentation_structure.prompt.md
   - path: role_contracts.prompt.md
   - path: task_model.prompt.md
+  - path: humans.md

package/package.json

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

package/policies/README.md

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

package/policies/codemap.yml

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

package/policies/definition-of-done.md

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

package/policies/definition-of-ready.md

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

package/policies/development-guidelines.md

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

package/policies/documentation-guidelines.md

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

package/policies/git-commit-messaging.md

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

package/policies/product-guidelines.md

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

package/policies/testing-guidelines.md

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

package/policies/ui-ux-guidelines.md

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

package/templates/optima.yaml.template

@@ -48,6 +48,9 @@ workflow:
       definition: Definition # Plan contract URL when native task-doc association is unavailable
       story_points: Story Points # WPM estimates during plan and re-estimates on material plan changes
       agent_metadata: agent_metadata # JSON session IDs per agent/type/task/subtask
+    definition_doc_parent:
+      doc_id: 2kxuv6pq-852
+      page_id: 2kxuv6pq-2292
     running_label: Running # Optional webhook mode uses local runtime state; enable only through explicit OpenCode ClickUp webhook config
     final_approval_roles:
       - CTO