@defend-tech/opencode-optima 0.1.71 → 0.1.73

package/docs/core/agent_orchestration.md

@@ -26,8 +26,9 @@
 - Human approval assignment is prohibited except for the strict allowlist: parent `plan` with clear questions already posted in ClickUp comments; `in progress` blocked by missing credentials, permissions, external tools, or access; or parent `validation` with a functional preview URL such as `https://<taskid>-preview.defend.tech`. Do not assign `CTO`/`PO` for generic handoff, routine validation, cleanup, subtask planning/validation, or partial-phase stops.
 - Store ClickUp `agent_metadata` JSON with session IDs per agent/type/task/subtask; keep `Definition` as the plan contract and final Documentation as delivered behavior docs.
 - `workflow_product_manager` is registered only when explicit ClickUp webhook mode is configured and the local webhook subscription state is active/valid.
-- Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, stores new `ses_...` ids in ClickUp `agent_metadata`, and reports stale/missing sessions to ClickUp without creating replacements.
-- The listener is a gated in-process HTTP listener for local runtime use; deployments still need a stable public URL/tunnel and local `.optima/.config/runtime/` state containing the ClickUp webhook id/secret. When a ClickUp client exposes webhook validation, Optima validates remote state; otherwise local-only validation is limited to ignored runtime state with matching URL/events and present id/secret.
+- Webhook mode is opt-in: Optima validates signed `X-Signature` HMAC SHA-256 ClickUp requests, routes status/assignee events only for Product Manager-assigned non-terminal tasks, routes comments only when they mention `@Defend Tech Product Manager`, and stores new `ses_...` ids in ClickUp `agent_metadata`. Runtime/process failures stay in local logs and must not create ClickUp comments or tags.
+- The same gated in-process listener can also accept signed GitHub `X-Hub-Signature-256` PR/review/comment events at `/optima/github/webhook` when `clickup.github.webhook` is enabled. GitHub events resolve the ClickUp task from the PR source branch, update only `agent_metadata.task.github`, and steer the existing `workflow_product_manager` session; they do not create replacement sessions or ClickUp runtime comments.
+- Deployments still need a stable public URL/tunnel and local `.optima/.config/runtime/` state containing the ClickUp webhook id/secret. When a ClickUp client exposes webhook validation, Optima validates remote state; otherwise local-only validation is limited to ignored runtime state with matching URL/events and present id/secret.
 
 ## Shared Worktree And Git
 

package/docs/core/agent_orchestration.prompt.md

@@ -19,8 +19,8 @@
 - Git rules: principal workspace stays on `dev`, never `main`; parent branches use `<type>/<parent-id>`; subtask branches use non-nested `<type>/<parent-id>-subtask-<subtask-id>` and pending subtasks use `<type>/<parent-id>-pending-<title-slug>`; parent task pulls remote once at start; subtasks start from and PR to the parent local branch, bootstrapping the parent from `dev`/`origin/dev` first when missing; PoC branches stay `poc/<clickup-task-id>`; parents PR to `dev`, releases PR `dev` -> `main`; failed/conflicted subtask or parent merges return the affected item to `in progress` for the coding owner; no direct `main` pushes.
 - Store `agent_metadata` session JSON; `Definition` is the plan contract, final Documentation is delivered behavior docs.
 - `workflow_product_manager` is registered only when opt-in ClickUp webhook mode is complete and active/valid.
-- Webhook mode validates `X-Signature` HMAC SHA-256, routes only PM-assigned non-terminal status/assignee events, routes comments only on `@Defend Tech Product Manager`, writes new `ses_...` ids to `agent_metadata`, and reports stale/missing sessions to ClickUp without replacement.
-- The listener is gated in-process local runtime; production needs a stable public URL/tunnel and ignored `.optima/.config/runtime/` webhook state. Remote webhook validation is used when the injected ClickUp client supports it; otherwise local-only validation is limited to matching id/secret/URL/events state.
+- Webhook mode validates ClickUp `X-Signature` HMAC SHA-256, routes only PM-assigned non-terminal status/assignee events, routes comments only on `@Defend Tech Product Manager`, writes new `ses_...` ids to `agent_metadata`, and keeps runtime/process failures in local logs, never ClickUp comments/tags.
+- The listener is gated in-process local runtime; production needs a stable public URL/tunnel and ignored `.optima/.config/runtime/` webhook state. It can also accept GitHub `X-Hub-Signature-256` PR/review/comment webhooks at `/optima/github/webhook`; these update only `agent_metadata.task.github` and steer the existing WPM session resolved from the PR source branch.
 - Communication: questions, blockers, reviews, dependencies, and escalation go through PMA. Tech Lead reviews architecture/code/PR/standards/repo skills; Validator/QA verifies tests/regression/coverage/evidence/docs.
 - Reopen same-scope discrepancies by reactivating the same task file, adding `Reopen History`, and reusing existing Task/Workflow Runner session IDs when possible.
 - Blockers move to `.optima/tasks/blocked/` with a clear blocker report and PO-facing resolution need.

package/docs/guides/AGENTS.md

@@ -61,3 +61,14 @@ Use shared policies and additive agent files by default. Do not create or popula
 - PMA links the task to an approved SCR.
 - Architect helps decompose the work into slice-based subtasks.
 - `workflow_runner` executes the end-to-end delivery cycle through specialist delegation while PMA waits for completion notification.
+
+## ClickUp-First PR And Preproduction Gate
+
+For ClickUp-first delivery, Validation is a GitHub PR state, not a comment-only handoff.
+
+- Subtasks open/update a PR from the subtask branch into the parent task branch before entering Validation.
+- Parent tasks open/update a PR from the task branch into `dev` before entering Validation.
+- GitHub review/comment webhooks wake the workflow owner. The agent replies in GitHub; if a comment requires a change, it moves ClickUp back to `in progress`, fixes/pushes the same branch, returns ClickUp to `validation`, updates the PR, and replies again with the result.
+- The configured final approver/CTO approving the parent PR is the merge trigger. After merge to `dev`, Vercel preproduction must deploy automatically and pass a small smoke/regression check before cleanup and ClickUp `completed`.
+- If merge, Vercel deployment, or regression fails, create Bug subtasks under the parent and return the parent to `in progress`.
+- Worktrees/branches may be deleted only after the merge and preproduction gate pass. OpenCode session ids remain in ClickUp `agent_metadata` so a reopened task can recreate the worktree and resume context.

package/package.json

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

package/templates/optima.yaml.template

@@ -67,5 +67,24 @@ workflow:
       subtask: parent_branch
       parent: dev
       release: main
+    validation_requires_pull_request: true # A task/subtask cannot enter Validation without an open GitHub PR
+    review_webhooks:
+      enabled: true
+      events:
+        - pull_request_review
+        - pull_request_review_comment
+        - issue_comment
+        - pull_request
+      comment_policy: reply_before_change_and_after_change
+      change_request_status: in progress
+      after_fix_status: validation
+      accepted_by: CTO
+  vercel:
+    preproduction:
+      required_for_parent_tasks: true
+      environment: preproduction
+      verify_deployment_after_merge: true
+      smoke_regression_required: true
+      on_failure: create_bug_subtasks_and_return_parent_to_in_progress
 
 agents: