@ddtcorex/dsh-maestro-review 0.3.2 → 0.5.0

package/src/host/providers/ci-trigger.ts

@@ -0,0 +1,164 @@
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { join } from 'node:path'
+import type { ReviewRequest, ReviewResult } from '../events.js'
+import { lastCompletedReview } from '../review-history.js'
+import type { ReviewSkillProfile } from '../skills-tool.js'
+import { gitlabAuthHeaders } from '../gitlab-auth.js'
+import { hasCompletedReviewForSha, hasRunningEyes } from '../ci-coexist.js'
+
+export const name = 'maestro-review-ci-trigger'
+export const inject = ['reviewRunner'] as const
+
+const REVIEW_PROFILES = ['magento2', 'laravel', 'symfony', 'wordpress', 'generic'] as const
+
+export interface CiEnvConfig {
+  gitlabBaseUrl: string
+  gitlabToken: string
+  sourceProjectId: number
+  mrIid: number
+  mode: 'quick' | 'deep'
+  dryRun: boolean
+  reviewProfile?: ReviewSkillProfile
+  /** Mirror of Settings UI autoRereviewOnPush (default off): re-review new pushes. */
+  rereviewOnPush: boolean
+}
+
+export const CiEnvConfig: z<CiEnvConfig> = z.object({
+  gitlabBaseUrl: z.string().required(),
+  gitlabToken: z.string().role('secret').required(),
+  sourceProjectId: z.number().required(),
+  mrIid: z.number().required(),
+  mode: z.union([z.const('quick'), z.const('deep')]).default('quick'),
+  dryRun: z.boolean().default(false),
+  reviewProfile: z.union([z.const('magento2'), z.const('laravel'), z.const('symfony'), z.const('wordpress'), z.const('generic')]),
+  rereviewOnPush: z.boolean().default(false),
+})
+
+/**
+ * Reads the CI contract env vars (spec §5.2) — not Cordis-supplied config, since these are
+ * per-run values a static profile config cannot hold. schemastery's `.required()` only rejects
+ * `undefined`, not an empty string, so GITLAB_HOST/MAESTRO_GITLAB_TOKEN presence is checked here
+ * before defaulting to `''` — otherwise a missing env var would silently pass validation.
+ */
+export function parseCiEnvConfig(env: Record<string, string | undefined>): CiEnvConfig {
+  if (env.GITLAB_HOST === undefined) throw new Error('missing GITLAB_HOST')
+  if (env.MAESTRO_GITLAB_TOKEN === undefined) throw new Error('missing MAESTRO_GITLAB_TOKEN')
+  if (env.REVIEW_PROFILE !== undefined && !(REVIEW_PROFILES as readonly string[]).includes(env.REVIEW_PROFILE)) {
+    throw new Error(`unsupported REVIEW_PROFILE "${env.REVIEW_PROFILE}" (supported: ${REVIEW_PROFILES.join(', ')})`)
+  }
+  return CiEnvConfig({
+    gitlabBaseUrl: `https://${env.GITLAB_HOST}`,
+    gitlabToken: env.MAESTRO_GITLAB_TOKEN,
+    sourceProjectId: Number(env.SOURCE_PROJECT_ID),
+    mrIid: Number(env.MR_IID),
+    mode: env.REVIEW_MODE === 'deep' ? 'deep' : 'quick',
+    dryRun: env.REVIEW_DRY_RUN === '1',
+    reviewProfile: env.REVIEW_PROFILE as ReviewSkillProfile | undefined,
+    rereviewOnPush: env.REVIEW_ON_PUSH === '1',
+  })
+}
+
+/** The one field a webhook payload carries that env vars don't — orchestrator fetches the diff itself. */
+export async function fetchMrSourceBranch(config: CiEnvConfig, fetcher: typeof fetch = fetch): Promise<string> {
+  return (await fetchMrDetail(config, fetcher)).sourceBranch
+}
+
+/** MR detail pieces CI needs in one call: source branch (worktree) + head SHA (push-gate). */
+export async function fetchMrDetail(config: CiEnvConfig, fetcher: typeof fetch = fetch): Promise<{ sourceBranch: string; headSha: string }> {
+  const url = `${config.gitlabBaseUrl}/api/v4/projects/${config.sourceProjectId}/merge_requests/${config.mrIid}`
+  const res = await fetcher(url, { headers: gitlabAuthHeaders(config.gitlabToken) })
+  if (!res.ok) throw new Error(`GitLab API error ${res.status}: ${await res.text()}`)
+  const body = await res.json() as { source_branch?: string; sha?: string }
+  if (typeof body.source_branch !== 'string') throw new Error('GitLab merge request response is missing source_branch')
+  if (typeof body.sha !== 'string') throw new Error('GitLab merge request response is missing sha')
+  return { sourceBranch: body.source_branch, headSha: body.sha }
+}
+
+export async function runCiTrigger(
+  ctx: Context,
+  config: CiEnvConfig,
+  deps: {
+    fetcher?: typeof fetch
+    writeFile?: typeof import('node:fs/promises').writeFile
+    history?: { lastCompletedReview(projectId: number, mrIid: number): Promise<{ headSha?: string } | undefined> }
+  } = {},
+): Promise<ReviewResult> {
+  const { sourceBranch, headSha } = await fetchMrDetail(config, deps.fetcher)
+  // Push-gate (mirror of the webhook autoRereviewOnPush semantics): the bridge fires
+  // on every MR pipeline, so skip when this exact head SHA already completed — and
+  // skip new pushes too unless REVIEW_ON_PUSH=1. A re-run then gets the H6 incremental
+  // block from history for free. Cache miss (no history) fails open toward running.
+  const history = deps.history ?? { lastCompletedReview }
+  const prior = await history.lastCompletedReview(config.sourceProjectId, config.mrIid)
+  let result: ReviewResult
+  if (prior?.headSha === headSha) {
+    result = { ok: true, summary: `already reviewed at ${headSha}, skipping`, failures: [], durationMs: 0 }
+  } else if (prior !== undefined && !config.rereviewOnPush) {
+    result = { ok: true, summary: `new commits since ${prior.headSha} but REVIEW_ON_PUSH is not set, skipping`, failures: [], durationMs: 0 }
+  } else {
+    // Coexistence (CI yields to webhook): the CI history store is invisible to
+    // the webhook flow and vice versa, so check the MR itself for a completed
+    // review marker of this SHA or an in-flight eyes marker before booting.
+    const coFetcher = deps.fetcher ?? fetch
+    if (await hasCompletedReviewForSha(coFetcher, config.gitlabBaseUrl, config.gitlabToken, config.sourceProjectId, config.mrIid, headSha)) {
+      result = { ok: true, summary: `webhook already reviewed ${headSha} — skipping`, failures: [], durationMs: 0 }
+    } else if (await hasRunningEyes(coFetcher, config.gitlabBaseUrl, config.gitlabToken, config.sourceProjectId, config.mrIid)) {
+      result = { ok: true, summary: 'another review is running — skipping', failures: [], durationMs: 0 }
+    } else {
+    // projectPath is synthetic (no webhook payload to read it from) — harmless: the
+    // reviewer-ci profile's own projectMappings is always [], so orchestrator's
+    // mapping lookup on projectPath never matches regardless of its exact value
+    // (same precedent as the PR #52 runner it replaces).
+    const request: ReviewRequest = {
+      projectPath: `project/${config.sourceProjectId}`,
+      projectId: config.sourceProjectId,
+      mrIid: config.mrIid,
+      sourceBranch,
+      headSha,
+      trigger: 'mention',
+      mode: config.mode,
+      scope: { kind: 'mr' },
+      reviewProfile: config.reviewProfile,
+    }
+    result = await ctx.reviewRunner(request)
+    }
+  }
+  const { writeFile } = deps.writeFile !== undefined ? { writeFile: deps.writeFile } : await import('node:fs/promises')
+  // entrypoint.sh cds into deepseek-harness before execing dsh, so a bare relative
+  // path would land inside the harness checkout (lost with the container). The
+  // entrypoint exports REVIEW_REPORT_DIR=$PWD captured before the cd, so reports land
+  // in the CI job's working directory where `artifacts:` picks them up.
+  const reportDir = process.env.REVIEW_REPORT_DIR?.trim() || '.'
+  const report = { ...result, projectId: config.sourceProjectId, mrIid: config.mrIid, mode: config.mode, generatedAt: new Date().toISOString() }
+  await writeFile(join(reportDir, 'review-report.json'), JSON.stringify(report, null, 2), 'utf-8')
+  const md = `# Review Report\n\n**Project:** ${config.sourceProjectId} !${config.mrIid}\n**Mode:** ${config.mode}\n**Duration:** ${result.durationMs}ms\n\n${result.summary ?? '(no summary)'}\n${result.failures.length > 0 ? `\nFailures:\n${result.failures.map(f => `- ${f}`).join('\n')}\n` : ''}`
+  await writeFile(join(reportDir, 'review-report.md'), md, 'utf-8')
+  return result
+}
+
+export function apply(ctx: Context): void {
+  ctx.effect(() => {
+    void (async () => {
+      try {
+        const config = parseCiEnvConfig(process.env)
+        console.log(`[review] ci-trigger starting: project ${config.sourceProjectId} !${config.mrIid} mode=${config.mode} dryRun=${config.dryRun}`)
+        const result = config.dryRun
+          ? { ok: true, summary: '[dry-run] config valid, skipping review', failures: [], durationMs: 0 }
+          : await runCiTrigger(ctx, config)
+        console.log(`[review] ci-trigger finished: ok=${result.ok} summary=${JSON.stringify(result.summary)} failures=${result.failures.length}`)
+        for (const failure of result.failures) console.error(`[review] ci-trigger failure: ${failure}`)
+        const exit = ctx.get('appExit')
+        if (exit === undefined) {
+          console.error('[review] ctx.get(\'appExit\') is undefined — the launcher did not provide it, process cannot signal its real exit code')
+        } else {
+          exit(result.ok ? 0 : 1)
+        }
+      } catch (err) {
+        console.error('maestro-review-ci-trigger:', err instanceof Error ? err.message : String(err))
+        ctx.get('appExit')?.(1)
+      }
+    })()
+    return () => {}
+  }, 'maestro-review-ci-trigger run')
+}

package/src/host/providers/gitlab.ts

@@ -128,7 +128,8 @@ export function apply(ctx: Context, config: Config): void {
         let body: GitlabMrWebhookBody; try { body = JSON.parse(raw) } catch { res.writeHead(400).end(); return }
         const userConfig = await loadUserConfig()
         if ((body.object_kind === 'merge_request' || body.object_kind === 'note') && !hasValidGitlabMrIdentity(body)) { res.writeHead(400).end(); return }
-        const request = routeGitlabReviewRequest(body, userConfig.botUsername ?? config.botUsername ?? 'maestro', { pushEnabled: userConfig.autoRereviewOnPush === true })
+        // The orchestrator is the sole push gate (resolveReviewTriggers); intake always emits.
+        const request = routeGitlabReviewRequest(body, userConfig.botUsername ?? config.botUsername ?? 'maestro', { pushEnabled: true })
         if (request !== undefined) ctx.emit('maestro/review-request', request)
         res.writeHead(200).end()
       })

package/src/host/review-findings-tool.ts

@@ -4,12 +4,18 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 export const name = 'maestro-review-findings-tool'
 export const inject = ['tools']
 
+export type FindingSeverity = 'blocking' | 'major' | 'minor' | 'nit'
+
 export interface ReviewFinding {
   status: 'new' | 'reply'
   body: string
   path?: string
   line?: number
   discussionId?: string
+  /** Assigned by the reviewer; missing values are treated as `minor`. */
+  severity?: FindingSeverity
+  /** Optional area tag, e.g. security, correctness, perf, style. */
+  category?: string
 }
 
 export interface Config {
@@ -19,7 +25,7 @@ export interface Config {
 export function apply(ctx: Context, config: Config): void {
   ctx.tools.register(defineTool({
     name: 'report_review_findings',
-    description: 'Submit your complete list of review findings exactly once, when done analyzing. Each finding is {status: "new", path, line, body} for a location with no existing thread, or {status: "reply", discussionId, body} to update an existing thread returned by gitlab_list_own_review_threads.',
+    description: 'Submit your complete list of review findings exactly once, when done analyzing. Each finding is {status: "new", path, line, body, severity, category?} for a location with no existing thread, or {status: "reply", discussionId, body, severity, category?} to update an existing thread returned by gitlab_list_own_review_threads (reply to a resolved thread reopens it — prefer reply over new when the substance matches). Severity (required in spirit, defaults to minor): blocking = must fix before merge (regression, data loss, real XSS/RCE); major = should fix (correctness bug, security hardening with a realistic path); minor = nice to fix (perf nit with impact, stale docs, fragile coupling); nit = style/micro with no behavior impact.',
     parameters: {
       findings: {
         type: 'array',
@@ -34,6 +40,8 @@ export function apply(ctx: Context, config: Config): void {
             path: { type: 'string' },
             line: { type: 'number' },
             discussionId: { type: 'string' },
+            severity: { type: 'string', enum: ['blocking', 'major', 'minor', 'nit'] },
+            category: { type: 'string' },
           },
         },
       },

package/src/host/review-intake.ts

@@ -81,6 +81,10 @@ export function routeGitlabReviewRequest(body: unknown, botUsername: string, opt
   if (value.object_kind !== 'note' || typeof attributes.note !== 'string' || !isMentioned(attributes.note, botUsername)) return undefined
   const scope = noteScope(attributes)
   if (scope === undefined) return undefined
-  const mode: ReviewMode = /(?:^|\s)\/maestro\s+deep(?:\s|$)/i.test(attributes.note) ? 'deep' : 'quick'
+  // Deep runs the auditor (env + perf) and costs far more than quick, so the
+  // trigger stays explicit: the `/maestro deep` slash command or the natural
+  // phrase "deep review". A bare "deep" alone never triggers (too loose).
+  const note = attributes.note
+  const mode: ReviewMode = /(?:^|\s)\/maestro\s+deep(?:\s|$)/i.test(note) || /\bdeep\s+review\b/i.test(note) ? 'deep' : 'quick'
   return { ...payload, trigger: 'mention', mode, scope }
 }

package/src/host/review-marker.ts

@@ -0,0 +1,25 @@
+/**
+ * Machine-readable review comment identity (spec: coexistence §4-5).
+ *
+ * Every posted review comment (webhook + CI, quick + deep) ends with an
+ * invisible marker so the CI flow can detect "this head SHA already has a
+ * completed review" without access to the webhook's history store.
+ */
+
+export type ReviewFlow = 'ci-quick' | 'ci-deep' | 'webhook'
+
+export function reviewMarker(sha: string, flow: ReviewFlow): string {
+  return `<!-- maestro-review sha=${sha} flow=${flow} status=completed -->`
+}
+
+export function parseReviewMarker(body: string): { sha: string; flow: string; status: string } | undefined {
+  const m = /<!-- maestro-review sha=([0-9a-fA-F]+) flow=([a-z-]+) status=([a-z]+) -->/.exec(body)
+  if (!m) return undefined
+  return { sha: m[1], flow: m[2], status: m[3] }
+}
+
+/** CI detection is env-based (established pattern): the reviewer job always sets these. */
+export function resolveFlow(mode: 'quick' | 'deep'): ReviewFlow {
+  if (process.env.SOURCE_PROJECT_ID === undefined) return 'webhook'
+  return mode === 'deep' ? 'ci-deep' : 'ci-quick'
+}

package/src/host/review-signals.ts

@@ -1,3 +1,4 @@
+import { gitlabAuthHeaders } from './gitlab-auth.js'
 /**
  * MR award-emoji acknowledgements: the MR shows "eyes" while a review runs and
  * a final marker when it completes or fails. Signalling is best-effort — any
@@ -12,7 +13,7 @@ export interface ReviewSignals {
 async function award(baseUrl: string, token: string, projectId: number, mrIid: number, name: string): Promise<void> {
   await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
     method: 'POST',
-    headers: { 'PRIVATE-TOKEN': token, 'Content-Type': 'application/json' },
+    headers: { ...gitlabAuthHeaders(token), 'Content-Type': 'application/json' },
     body: JSON.stringify({ name }),
   })
 }
@@ -20,7 +21,7 @@ async function award(baseUrl: string, token: string, projectId: number, mrIid: n
 /** Remove only this bot's stale running markers; other users' awards stay untouched. */
 async function unawardOwn(baseUrl: string, token: string, projectId: number, mrIid: number, botUsername: string): Promise<void> {
   const response = await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji`, {
-    headers: { 'PRIVATE-TOKEN': token },
+    headers: gitlabAuthHeaders(token),
   })
   if (!response.ok) return
   const awards = (await response.json()) as Array<{ id?: number; name?: string; user?: { username?: string } }>
@@ -28,7 +29,7 @@ async function unawardOwn(baseUrl: string, token: string, projectId: number, mrI
     if (awardItem.name !== 'eyes' || awardItem.user?.username !== botUsername || typeof awardItem.id !== 'number') continue
     await fetch(`${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}/award_emoji/${awardItem.id}`, {
       method: 'DELETE',
-      headers: { 'PRIVATE-TOKEN': token },
+      headers: gitlabAuthHeaders(token),
     }).catch(() => {})
   }
 }

package/src/host/settings-rpc.ts

@@ -12,7 +12,7 @@ export const inject = ['connection', 'maestroTunnel']
 /** Keys the Settings card may persist; anything else is a rejected save. */
 const SAVABLE_KEYS = new Set<keyof MaestroUserConfig>([
   'gitlabBaseUrl', 'gitlabToken', 'botUsername', 'webhookSecret', 'webhookPort',
-  'projectMappings', 'reviewModel', 'autoRereviewOnPush', 'agentTimeoutMs', 'reviewSessionRetentionDays',
+  'projectMappings', 'reviewModel', 'autoRereviewOnPush', 'autoReviewOnAssign', 'agentTimeoutMs', 'reviewSessionRetentionDays',
   'tunnelMode', 'quickTarget', 'tunnelId', 'tunnelCredentialsFile', 'tunnelHostname',
   'proxyPort', 'proxyHost', 'lanPinEnabled', 'telegramBotToken', 'telegramChatId',
   'telegramReviewNotifications',

package/templates/reviewer-project.gitlab-ci.yml

@@ -0,0 +1,90 @@
+# ddtcorex/maestro-reviewer — dedicated reviewer project
+stages: [review]
+
+variables:
+  # Image registry — pin the SHA for reproducibility
+  REVIEWER_IMAGE: "ddtcorex/maestro-reviewer:latest"
+  # Or use $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA when building the image in the same project
+
+review:
+  stage: review
+  image: $REVIEWER_IMAGE
+  # Only runs when triggered from the source project (or manually)
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "pipeline"          # bridge trigger
+    - if: $CI_PIPELINE_SOURCE == "trigger"           # token trigger
+    - if: $CI_PIPELINE_SOURCE == "web"               # manual retry
+      when: manual
+  variables:
+    GIT_STRATEGY: none   # no need to check out the reviewer repo
+  # Every parameter comes from env (SOURCE_PROJECT_ID, MR_IID, GITLAB_HOST, REVIEW_MODE) — no CLI args.
+  script:
+    - /entrypoint.sh
+  # History cache — the push-gate (skip already-reviewed head SHAs) and incremental
+  # context read $DSH_HOME/dsh-maestro-review/reviews.json, which is ephemeral in a
+  # fresh container. entrypoint.sh symlinks it at this cached path (one store, many
+  # MRs — entries are keyed per MR inside). Cache miss fails open toward reviewing.
+  cache:
+    key: maestro-review-history
+    paths:
+      - .maestro-history/
+  artifacts:
+    when: always
+    expire_in: 1 week
+    paths:
+      - review-report.json
+      - review-report.md
+  # Secrets — Protected + Masked, only available on the reviewer project's protected branches.
+  # MAESTRO_GITLAB_TOKEN is REQUIRED and must be a user PAT or Group/Project
+  # Access Token (api scope). CI_JOB_TOKEN is NOT enough: proven 2026-09-04 on
+  # GitLab 18.11 that reads work (GET=200) but posting the review comment fails
+  # (POST /notes=401) even with the source project allowlisting this reviewer —
+  # the run would "complete" without ever posting. A human-tied PAT needs yearly
+  # rotation; prefer a bot/group token where the instance allows creating one.
+  # MAESTRO_GITLAB_TOKEN (api scope) — required
+  # Route selection is key-based (entrypoint.sh swaps the baked settings variant):
+  # OPENCODE_GO_API_KEY → opencode profile (default, host mirror; serves opencode-go
+  #   AND deepseek-official-via-zen). Set alone, or with DEEPSEEK_API_KEY (opencode wins).
+  # DEEPSEEK_API_KEY → deepseek profile ONLY when OPENCODE_GO_API_KEY is absent
+  #   (deepseek-official straight from api.deepseek.com — needs a LIVE deepseek.com key).
+  # TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID (optional)
+  # Opencode model (optional, one variable — default muse-spark-1.3-contributor):
+  # OPENCODE_MODEL: "muse-spark-1.3-contributor"
+  # Model pin (optional, as a pair — unset both for the host-mirrored default
+  #   = opencode-go/muse-spark-1.3-contributor, baked in docker/ci-settings.yaml):
+  # REVIEW_MODEL_PROVIDER: "opencode-go"             # or "deepseek-official"
+  # REVIEW_MODEL: "muse-spark-1.3-contributor"       # e.g. deepseek-v4-flash (deepseek-official via zen)
+  #   Only the provider's key is needed — no settings mount required. ID without
+  #   provider fails the review with a provider error (not silently the wrong
+  #   model); provider without ID is ignored.
+  # Review skill profile (optional — unset for the legacy diff-only generic review):
+  # REVIEW_PROFILE: "magento2"                       # magento2 | laravel | symfony | wordpress | generic
+  #   The reviewer must load the full skill set or the review fails closed
+  #   (no half-skilled review). Runtime-backed checks still degrade without a
+  #   checkout — the profile adds framework checklists, not a govard run.
+  # Review mode (default quick; deep runs on demand — no new variables):
+  # REVIEW_MODE: "deep"                              # manual downstream run with the same
+  #   bridge variables (SOURCE_PROJECT_ID, MR_IID, GITLAB_HOST) + REVIEW_ON_PUSH=1
+  #   to re-review pushes. The job clones the source at the MR head SHA with
+  #   MAESTRO_GITLAB_TOKEN (api scope, oauth2) and runs reviewer (+auditor
+  #   degraded to reviewer-only without a runtime). No govard in the container.
+  #   CI yields to webhook: if the head SHA already has a completed review
+  #   comment (either flow), the run skips instead of double-posting.
+  # Re-review pushes (optional — mirrors Settings UI autoRereviewOnPush, default off):
+  # REVIEW_ON_PUSH: "1"                              # re-review new pushes with incremental context;
+  #   unset = only the first (opened) review runs; same head SHA always skips.
+
+# Build the image inside the same reviewer project (optional):
+#
+# build:image:
+#   stage: .pre
+#   image: docker:27
+#   services: [docker:27-dind]
+#   rules:
+#     - if: $CI_COMMIT_BRANCH == "main"
+#   script:
+#     - docker build -f packages/dsh-maestro-review/docker/Dockerfile -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA -t $CI_REGISTRY_IMAGE:latest .
+#     - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+#     - docker push $CI_REGISTRY_IMAGE:latest
+#   # Build context must be the maestro-harness workspace root (contains deepseek-harness/) —
+#   # the trailing "." above assumes this job checks out maestro-harness, not this repo alone.

package/templates/source-project.gitlab-ci.yml

@@ -0,0 +1,42 @@
+# example-group/example-project — source project (copy this template into YOUR source project)
+stages: [review]
+
+# Only runs when there is an MR (fork MRs run fine too — this job has no secrets)
+maestro:trigger-review:
+  stage: review
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  # No image needed, no secrets needed
+  trigger:
+    project: ddtcorex/maestro-reviewer   # ← reviewer project path
+    branch: main                          # ← the reviewer project's default branch (master on some instances)
+    strategy: depend                      # optional: wait for the reviewer pipeline, surface its status on the MR
+  variables:
+    SOURCE_PROJECT_ID: $CI_PROJECT_ID
+    MR_IID: $CI_MERGE_REQUEST_IID
+    GITLAB_HOST: $CI_SERVER_HOST
+    SOURCE_SHA: $CI_COMMIT_SHA
+    REVIEW_MODE: "quick"                 # or "deep" for a govard audit
+    REVIEW_PROFILE: "generic"            # per-project skill profile: magento2 | laravel | symfony | wordpress | generic
+    # REVIEW_ON_PUSH: "1"               # uncomment to re-review every push (default: only the opened review runs)
+
+# Trigger Token fallback (when not using `trigger: project:`):
+#
+# maestro:trigger-review:token:
+#   stage: review
+#   rules:
+#     - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+#   image: curlimages/curl:8
+#   variables:
+#     REVIEWER_PROJECT_ID: "123"  # id of the maestro-reviewer project
+#   script:
+#     - |
+#       curl --fail --request POST \
+#         --form token=$MAESTRO_TRIGGER_TOKEN \
+#         --form ref=main \
+#         --form variables[SOURCE_PROJECT_ID]=$CI_PROJECT_ID \
+#         --form variables[MR_IID]=$CI_MERGE_REQUEST_IID \
+#         --form variables[GITLAB_HOST]=$CI_SERVER_HOST \
+#         "https://${CI_SERVER_HOST}/api/v4/projects/${REVIEWER_PROJECT_ID}/trigger/pipeline"
+#   # MAESTRO_TRIGGER_TOKEN is the reviewer project's Trigger Token, stored in the source project
+#   # (can only trigger, never read/write code — safer than GITLAB_TOKEN)