@ddtcorex/dsh-maestro-review 0.3.2 → 0.5.0

package/src/host/orchestrator.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile } from 'node:fs/promises'
+import { mkdir, writeFile, symlink, stat, lstat } from 'node:fs/promises'
 import { execFile } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { promisify } from 'node:util'
@@ -29,9 +29,9 @@ import * as ScopeSplitTool from './scope-split-tool.js'
 import * as GovardAuditLintTool from './govard-audit-lint-tool.js'
 import * as PerfLogStatsTool from './perf-log-stats-tool.js'
 import * as ReviewToolPolicy from './tool-policy.js'
-import type { ReviewFinding } from './review-findings-tool.js'
-import type { ReviewRequest } from './events.js'
-import { loadUserConfig, type MaestroUserConfig, type ReviewModelSelection } from './config-store.js'
+import type { ReviewFinding, FindingSeverity } from './review-findings-tool.js'
+import type { ReviewRequest, ReviewResult } from './events.js'
+import { loadUserConfig, type MaestroUserConfig, type ProjectMapping, type ReviewModelSelection } from './config-store.js'
 import { hasCompletedReview, lastCompletedReview, pruneHistory, recordReviewFinish, recordReviewStart } from './review-history.js'
 import { buildIncrementalBlock, fetchCompare, fetchMrDetailHeadSha } from './incremental.js'
 import { createReviewSignals } from './review-signals.js'
@@ -40,6 +40,9 @@ import { loadedReviewProfile, type ReviewSkillProfile } from './skills-tool.js'
 import type { ReviewProvider } from './providers/interface.js'
 import { gitlabProvider } from './providers/gitlab.js'
 import './events.js'
+import { gitlabAuthHeaders } from './gitlab-auth.js'
+import { reviewMarker, resolveFlow, type ReviewFlow } from './review-marker.js'
+import { cloneSourceRepo, defaultRun } from './ci-clone.js'
 
 // Provider-aware wrapper — orchestrator can run reviews via any ReviewProvider.
 // This keeps the GitLab-specific flow intact while allowing Phase C to add GitHub/Jira without modifying core logic.
@@ -58,6 +61,62 @@ export { gitlabProvider }
 const execFileAsync = promisify(execFile)
 const GIT_TIMEOUT_MS = 60_000
 
+/**
+ * Finding severity, assigned by the reviewer. Display order is fixed
+ * (blocking first) wherever counts are rendered.
+ */
+export const SEVERITY_ORDER: readonly FindingSeverity[] = ['blocking', 'major', 'minor', 'nit'] as const
+
+const SEVERITY_LABEL: Record<FindingSeverity, string> = {
+  blocking: '🔴 Blocking',
+  major: '🟡 Major',
+  minor: '🔵 Minor',
+  nit: '⚪ Nit',
+}
+
+/** Missing or unknown severities degrade to `minor` — never drop a finding. */
+export function normalizeFindingSeverity(severity: unknown): FindingSeverity {
+  return severity === 'blocking' || severity === 'major' || severity === 'minor' || severity === 'nit'
+    ? severity
+    : 'minor'
+}
+
+export function severityPrefix(severity: unknown): string {
+  return SEVERITY_LABEL[normalizeFindingSeverity(severity)]
+}
+
+/** Count findings per severity; zero counts are omitted. */
+export function countFindingSeverities(findings: ReviewFinding[]): Partial<Record<FindingSeverity, number>> {
+  const counts: Partial<Record<FindingSeverity, number>> = {}
+  for (const finding of findings) {
+    const level = normalizeFindingSeverity(finding.severity)
+    counts[level] = (counts[level] ?? 0) + 1
+  }
+  return counts
+}
+
+export interface ReviewerScopePromptOpts {
+  scopeKind: 'discussion' | 'full'
+  discussionId?: string
+  path?: string
+  line?: number
+  mode?: string
+  profileInstruction: string
+}
+
+/**
+ * Reviewer scope prompt. Static analysis is mandatory: reviewers skipped
+ * govard_audit_lint for whole rounds (no lint signal at all), so the prompt
+ * requires at least one call before report_review_findings. Pure for testing.
+ */
+export function buildReviewerScopePrompt(opts: ReviewerScopePromptOpts): string {
+  const lintRule = 'LINT RULE: you MUST call govard_audit_lint at least once (scope "diff"; the MR base default is already wired, no base arg needed) before report_review_findings. A review with no lint call is incomplete.'
+  if (opts.scopeKind === 'discussion') {
+    return `${opts.profileInstruction}Review only the requested inline discussion ${opts.discussionId} at ${opts.path}:${opts.line}. Do not review unrelated files or start a broad audit. Call gitlab_get_mr_diff, then gitlab_get_file_diff for the file under review, then call report_review_findings exactly once when done. ${lintRule}`
+  }
+  return `${opts.profileInstruction}Review this merge request (${opts.mode} mode). Call gitlab_list_own_review_threads and gitlab_get_mr_diff first, then gitlab_get_file_diff per file you inspect (inline results never spill), then call report_review_findings exactly once when done. ${lintRule} DEDUP RULE: when a finding matches the substance of an existing own thread (same file and same underlying issue, even if worded differently — including resolved threads, whose reply reopens them), report it as {status: "reply", discussionId} instead of posting a new thread. Use status "new" only for issues with no matching thread.`
+}
+
 /**
  * Build a user-friendly GitLab Markdown comment for a completed review.
  * Shared design language with `reviewDigestText` (Telegram HTML) — same
@@ -72,10 +131,11 @@ export function buildReviewComment(opts: {
   profile?: string
   summary: string
   failures: string[]
-  findings?: { newCount: number; replyCount: number }
+  findings?: { newCount: number; replyCount: number; severityCounts?: Partial<Record<FindingSeverity, number>> }
   durationMs?: number
   isDiffOnly?: boolean
   isDiscussion?: boolean
+  marker?: { sha: string; flow: ReviewFlow }
 }): string {
   const mrUrl = `${opts.gitlabBaseUrl.replace(/\/$/, '')}/${opts.projectPath}/-/merge_requests/${opts.mrIid}`
   const title = opts.isDiffOnly === true ? '## 🤖 Maestro Review — Diff-only' : '## 🤖 Maestro Review'
@@ -97,6 +157,12 @@ export function buildReviewComment(opts: {
         const parts: string[] = []
         if (opts.findings.newCount > 0) parts.push(`💬 ${opts.findings.newCount} new`)
         if (opts.findings.replyCount > 0) parts.push(`🔁 ${opts.findings.replyCount} updated`)
+        if (opts.findings.severityCounts !== undefined) {
+          for (const level of SEVERITY_ORDER) {
+            const count = opts.findings.severityCounts[level] ?? 0
+            if (count > 0) parts.push(`${SEVERITY_LABEL[level].split(' ')[0]} ${count} ${level}`)
+          }
+        }
         if (parts.length === 0) parts.push('no inline findings')
         return `\n\n**Findings:** ${parts.join(' · ')}`
       })()
@@ -105,10 +171,11 @@ export function buildReviewComment(opts: {
     ? `\n\n<details>\n<summary>⚠️ Failed to post (${opts.failures.length})</summary>\n\n${opts.failures.map((f) => `- \`${f}\``).join('\n')}\n\n</details>`
     : ''
   const footer = `\n\n---\n\n<sub>Generated by Maestro · [View MR →](${mrUrl})</sub>`
-  return `${title}\n\n${metaLine}\n\n${scopeNote}${opts.summary}${findingsLine}${failuresBlock}${footer}`
+  const markerLine = opts.marker === undefined ? '' : `\n\n${reviewMarker(opts.marker.sha, opts.marker.flow)}`
+  return `${title}\n\n${metaLine}\n\n${scopeNote}${opts.summary}${findingsLine}${failuresBlock}${footer}${markerLine}`
 }
 
-export function buildNotStartedComment(opts: { gitlabBaseUrl: string; projectPath: string; mrIid: number }): string {
+export function buildNotStartedComment(opts: { gitlabBaseUrl: string; projectPath: string; mrIid: number; marker?: { sha: string; flow: ReviewFlow } }): string {
   const mrUrl = `${opts.gitlabBaseUrl.replace(/\/$/, '')}/${opts.projectPath}/-/merge_requests/${opts.mrIid}`
   return [
     '## 🤖 Maestro Review — Not started',
@@ -121,6 +188,7 @@ export function buildNotStartedComment(opts: { gitlabBaseUrl: string; projectPat
     `---`,
     '',
     `<sub>Generated by Maestro · [View MR →](${mrUrl})</sub>`,
+    ...(opts.marker === undefined ? [] : [``, `${reviewMarker(opts.marker.sha, opts.marker.flow)}`]),
   ].join('\n')
 }
 
@@ -168,14 +236,17 @@ export function getTurnErrorMessage(handle: unknown): string | undefined {
 
 /**
  * Resolve the model to use for an automated review. Priority: per-project
- * override > global reviewModel > DSH default (`fallback`).
+ * override > global reviewModel (Maestro Settings) > row-config reviewModel
+ * (lets a headless profile such as reviewer-ci pin a model from env vars,
+ * where there is no Settings UI) > DSH default (`fallback`).
  */
 export function resolveReviewModel(
   userConfig: MaestroUserConfig,
-  mapping: { reviewModel?: ReviewModelSelection | null } & Record<string, unknown> | undefined,
+  mapping: { reviewModel?: ReviewModelSelection | null; projectPath?: string } | undefined,
   fallback: ModelSelection,
+  rowSelection?: ReviewModelSelection | null,
 ): ModelSelection {
-  const raw = (mapping?.reviewModel as ReviewModelSelection | null | undefined) ?? userConfig.reviewModel
+  const raw = (mapping?.reviewModel as ReviewModelSelection | null | undefined) ?? userConfig.reviewModel ?? rowSelection
   if (raw === undefined || raw === null) return fallback
   return {
     provider: raw.provider,
@@ -184,6 +255,17 @@ export function resolveReviewModel(
   }
 }
 
+/** Effective auto-trigger flags: per-project row overrides global, unset inherits (design §4). */
+export function resolveReviewTriggers(
+  userConfig: MaestroUserConfig,
+  mapping?: ProjectMapping,
+): { onPush: boolean; onAssign: boolean } {
+  return {
+    onPush: mapping?.rereviewOnPush ?? userConfig.autoRereviewOnPush ?? false,
+    onAssign: mapping?.reviewOnAssign ?? userConfig.autoReviewOnAssign ?? true,
+  }
+}
+
 /** Compose a newly-created agent from the preset service owned by the root context. */
 export async function mountAgentPreset(
   agentPresets: { mount(agentCtx: Context, id: string): Promise<unknown> | unknown },
@@ -204,6 +286,19 @@ export interface Config {
   botUsername: string
   /** Hard ceiling on one automated agent's turn. */
   agentTimeoutMs: number
+  /**
+   * Deployment-level model pin, below Maestro Settings in precedence. Lets a
+   * headless profile (reviewer-ci) select the review model from env vars —
+   * e.g. REVIEW_MODEL_PROVIDER/REVIEW_MODEL — where no Settings UI exists.
+   *
+   * Deliberately absent from the zod schema below: schemastery object schemas
+   * always descend into inner fields (probed — even `.required(false)` still
+   * throws on undefined), so declaring it would fail every boot without the
+   * vars. Unknown keys pass validation through (same precedent as mapping-level
+   * reviewModel, which the projectMappings schema doesn't declare either),
+   * and resolveReviewModel reads it at review time.
+   */
+  reviewModel?: ReviewModelSelection | null
 }
 
 export const DEFAULT_AGENT_TIMEOUT_MS = 20 * 60_000
@@ -223,6 +318,7 @@ export const Config: z<Config> = z.object({
 export interface ReviewOutcome {
   summary: string
   failures: string[]
+  severityCounts?: Partial<Record<FindingSeverity, number>>
 }
 
 /**
@@ -371,13 +467,15 @@ function normalizedDiffPath(path: string): string {
 export async function postReviewFindings(findings: ReviewFinding[], config: GitlabFindingPoster): Promise<void> {
   const fetcher = config.fetcher ?? fetch
   const apiBase = `${config.baseUrl}/api/v4/projects/${config.projectId}/merge_requests/${config.mrIid}`
-  const headers = { 'PRIVATE-TOKEN': config.token, 'Content-Type': 'application/json' }
+  const headers = { ...gitlabAuthHeaders(config.token), 'Content-Type': 'application/json' }
   for (const finding of findings) {
     let response: Response
+    const label = severityPrefix(finding.severity)
+    const body = finding.body.startsWith(label) ? finding.body : `${label}\n\n${finding.body}`
     if (finding.status === 'reply') {
       if (finding.discussionId === undefined) throw new Error('reply finding missing discussionId')
       response = await fetcher(`${apiBase}/discussions/${encodeURIComponent(finding.discussionId)}/notes`, {
-        method: 'POST', headers, body: JSON.stringify({ body: finding.body }),
+        method: 'POST', headers, body: JSON.stringify({ body }),
       })
     } else {
       if (finding.path === undefined || finding.line === undefined) throw new Error('new finding missing path or line')
@@ -395,12 +493,12 @@ export async function postReviewFindings(findings: ReviewFinding[], config: Gitl
         // Line not in diff — fallback to MR note so finding is not silently lost.
         response = await fetcher(`${apiBase}/notes`, {
           method: 'POST', headers,
-          body: JSON.stringify({ body: `**Inline fallback — \`${finding.path}:${finding.line}\` line is not in current MR diff**\n\n${finding.body}` }),
+          body: JSON.stringify({ body: `**Inline fallback — \`${finding.path}:${finding.line}\` line is not in current MR diff**\n\n${body}` }),
         })
       } else {
         response = await fetcher(`${apiBase}/discussions`, {
           method: 'POST', headers,
-          body: JSON.stringify({ body: finding.body, position: {
+          body: JSON.stringify({ body, position: {
             position_type: 'text', ...snapshot.diffRefs, old_path: change.old_path, new_path: change.new_path,
             ...linePosition.oldLine === undefined ? {} : { old_line: linePosition.oldLine },
             ...linePosition.newLine === undefined ? {} : { new_line: linePosition.newLine },
@@ -453,7 +551,91 @@ function assertSafeId(value: number, label: string): void {
   }
 }
 
+/**
+ * Read an agent session's transcript for the auditor's final output across
+ * host/session API skew: hosts built from the harness checkout expose
+ * `ownEvents()`/`snapshotEvents()` with no `.events` getter, while older
+ * packaged `@deepseek-ai/dsh-session` builds expose only the `.events`
+ * getter. `ownEvents()` (child-owned suffix, no fork prefix) matches
+ * `finalAssistantOutput`'s documented input best, so it wins when present.
+ * Returns `[]` — never throws — when no event source exists.
+ */
+export function auditorOutputFromSession(session: unknown) {
+  const candidate = session as {
+    ownEvents?: unknown
+    snapshotEvents?: unknown
+    events?: unknown
+  } | null | undefined
+  let events: unknown
+  if (typeof candidate?.ownEvents === 'function') {
+    events = (candidate.ownEvents as () => unknown)()
+  } else if (typeof candidate?.snapshotEvents === 'function') {
+    events = (candidate.snapshotEvents as () => unknown)()
+  } else {
+    events = candidate?.events
+  }
+  if (!Array.isArray(events)) return []
+  return finalAssistantOutput(events as Parameters<typeof finalAssistantOutput>[0]) ?? []
+}
+
 /** Full review + performance audit; resolves to the comment body that was posted. */
+/** Marker for CI-posted comments; webhook payloads carry no headSha and stay marker-free. */
+function commentMarker(payload: ReviewRequest): { sha: string; flow: ReviewFlow } | undefined {
+  if (payload.headSha === undefined) return undefined
+  return { sha: payload.headSha, flow: resolveFlow(payload.mode) }
+}
+
+/** CI-deep decision: deep mode + CI env + head SHA (spec §3). Mapping is checked by the caller. */
+export function shouldCiDeepReview(payload: ReviewRequest): boolean {
+  return payload.mode === 'deep'
+    && payload.headSha !== undefined
+    && process.env.SOURCE_PROJECT_ID !== undefined
+    && process.env.MR_IID !== undefined
+}
+
+/** CI quick-with-profile decision: quick mode + non-generic profile + CI env
+ *  + head SHA. Quick + generic/unset stays diff-only (no clone cost); a real
+ *  profile opts into the clone branch reviewer-only (no auditor — quick never
+ *  audits, see shouldAudit in runReviewAndAudit). Mapping is checked by the caller. */
+export function shouldCiQuickProfileReview(payload: ReviewRequest): boolean {
+  return payload.mode === 'quick'
+    && payload.reviewProfile !== undefined
+    && payload.reviewProfile !== 'generic'
+    && payload.headSha !== undefined
+    && process.env.SOURCE_PROJECT_ID !== undefined
+    && process.env.MR_IID !== undefined
+}
+
+/** Auditor degrade for CI (no runtime env): a govard throw becomes reviewer-only, never a failed review. */
+export function withAuditorDegrade(
+  runAuditor: (worktreePath: string, payload: ReviewRequest) => Promise<string>,
+): (worktreePath: string, payload: ReviewRequest) => Promise<string> {
+  return async (worktreePath, payload) => {
+    try {
+      return await runAuditor(worktreePath, payload)
+    } catch {
+      return 'Auditor skipped — no runtime environment in CI (reviewer-only review).'
+    }
+  }
+}
+
+/**
+ * Auditor instruction. The mapped flow keeps the full environment + test-suite
+ * workflow; the CI flow has no runtime, so the prompt countermands the
+ * auditor preset's environment steps and drops the Environment & Test Suite
+ * section entirely instead of reporting it "blocked".
+ */
+export function buildAuditorPrompt(opts: { staticOnly: boolean }): string {
+  if (!opts.staticOnly) {
+    return 'Audit this merge request\'s performance: bring up the environment, run the test suite, look for regressions, then write a Markdown report and tear the environment down.'
+  }
+  return 'Audit this merge request\'s performance from the static diff and checked-out code only. '
+    + 'No runtime environment exists in this container: ignore the auditor preset\'s environment steps '
+    + '(do not bring anything up, do not run the test suite, do not tear anything down). '
+    + 'Look for regressions by static analysis (diff, dependencies, query/shape risks), then write a Markdown report '
+    + 'and OMIT the Environment & Test Suite section entirely — never report it as blocked.'
+}
+
 export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndAuditDeps): Promise<string> {
   assertSafeId(payload.projectId, 'projectId')
   assertSafeId(payload.mrIid, 'mrIid')
@@ -471,7 +653,7 @@ export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndA
       ])
       const labels = ['Reviewer', 'Auditor']
       if (settled[0].status === 'fulfilled') {
-        const { summary, failures } = settled[0].value
+        const { summary, failures, severityCounts } = settled[0].value
         // Try to parse findings counts from summary like "2 new inline comment(s), 1 thread(s) updated."
         const summaryText = summary ?? ''
         const newMatch = /(\d+)\s+new inline/.exec(summaryText)
@@ -488,7 +670,8 @@ export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndA
               profile: (deps as unknown as { reviewProfile?: string }).reviewProfile,
               summary: summaryText,
               failures,
-              findings: { newCount, replyCount },
+              findings: { newCount, replyCount, severityCounts },
+              marker: commentMarker(payload),
             })
           : `## 🤖 Maestro Review\n\n**\`${payload.projectPath}\` !${payload.mrIid}** · ✅ Completed · \`${payload.mode}\`${(deps as unknown as { reviewProfile?: string }).reviewProfile !== undefined ? ` · \`${(deps as unknown as { reviewProfile: string }).reviewProfile}\`` : ''}\n\n${summaryText}${failures.length > 0 ? `\n\n<details>\n<summary>⚠️ Failed to post (${failures.length})</summary>\n\n${failures.map((f) => `- \`${f}\``).join('\n')}\n\n</details>` : ''}`
         sections.push(richOpts)
@@ -505,7 +688,8 @@ export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndA
       try {
         if (payload.scope.kind === 'discussion') await deps.replyToDiscussion(payload.scope.discussionId, body)
         else await deps.postComment(body)
-      } catch {
+      } catch (err) {
+        console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
         await deps.writeFailedReport(payload.mrIid, body)
       }
       return body
@@ -540,13 +724,15 @@ export async function runDiffOnlyReview(payload: ReviewRequest, deps: DiffOnlyRe
           summary: summary ?? '',
           failures,
           isDiffOnly: true,
+          marker: commentMarker(payload),
         })
       : `## 🤖 Maestro Review — Diff-only\n\n> **Scope:** Diff-only — reviewed the GitLab diff without a local checkout, Magento environment, static analysis, or tests. For a full review, add this project in Settings → Maestro and mention again.\n\n${summary}${failures.length > 0 ? `\n\n<details>\n<summary>⚠️ Failed to post (${failures.length})</summary>\n\n${failures.map((f) => `- \`${f}\``).join('\n')}\n\n</details>` : ''}`
     const body = diffBody
     try {
       if (payload.scope.kind === 'discussion') await deps.replyToDiscussion(payload.scope.discussionId, body)
       else await deps.postComment(body)
-    } catch {
+    } catch (err) {
+      console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
       await deps.writeFailedReport(payload.mrIid, body)
     }
     return body
@@ -565,13 +751,14 @@ export async function declineUnmappedDeepReview(payload: ReviewRequest, deps: Re
   const depsWithUrl = deps as unknown as { gitlabBaseUrl?: string; projectPath?: string }
   const baseUrl = depsWithUrl.gitlabBaseUrl
   const body = baseUrl !== undefined
-    ? buildNotStartedComment({ gitlabBaseUrl: baseUrl, projectPath: payload.projectPath, mrIid: payload.mrIid })
+    ? buildNotStartedComment({ gitlabBaseUrl: baseUrl, projectPath: payload.projectPath, mrIid: payload.mrIid, marker: commentMarker(payload) })
     : '## 🤖 Maestro Review — Not started\n\n**`' + payload.projectPath + '` !' + payload.mrIid + '** · ⏸️ Not started\n\n> Deep review requires a project mapping with a local checkout and Magento environment.\n> Add this project in **Settings → Maestro**, then mention the reviewer again.'
   try {
     try {
       if (payload.scope.kind === 'discussion') await deps.replyToDiscussion(payload.scope.discussionId, body)
       else await deps.postComment(body)
-    } catch {
+    } catch (err) {
+      console.error(`maestro-orchestrator: posting review comment failed: ${err instanceof Error ? err.message : String(err)}`)
       await deps.writeFailedReport(payload.mrIid, body)
     }
   } finally {
@@ -619,7 +806,34 @@ export function isBranchNotFoundError(err: unknown): boolean {
  */
 export function govardWorktreeOverride(projectId: number, mrIid: number, keySuffix?: string): string {
   const name = `maestro-mr-${projectId}-${mrIid}${keySuffix === undefined ? '' : `-${keySuffix}`}`
-  return `project_name: ${name}\ndomain: ${name}.test\n`
+  // Xdebug stays off in review envs: the auditor runs no coverage, and an
+  // enabled Xdebug trips govard's lint perf-tax guard (exit 1, 0 findings).
+  return `project_name: ${name}\ndomain: ${name}.test\nstack:\n  features:\n    xdebug: false\n`
+}
+
+/**
+ * Fetch the MR's diff base SHA for govard diff-scope runs. Best-effort:
+ * returns undefined (the lint tool then fail-fasts with guidance) rather
+ * than failing the review when GitLab is unreachable.
+ */
+export async function fetchMrBaseSha(
+  baseUrl: string,
+  token: string,
+  projectId: number,
+  mrIid: number,
+  fetcher: typeof fetch = fetch,
+): Promise<string | undefined> {
+  try {
+    const response = await fetcher(
+      `${baseUrl}/api/v4/projects/${projectId}/merge_requests/${mrIid}`,
+      { headers: gitlabAuthHeaders(token) },
+    )
+    if (!response.ok) return undefined
+    const mr = await response.json() as { diff_refs?: { base_sha?: string } }
+    return mr.diff_refs?.base_sha
+  } catch {
+    return undefined
+  }
 }
 
 export async function ensureWorktree(localRepoPath: string, sourceBranch: string, projectId: number, mrIid: number, keySuffix?: string): Promise<string> {
@@ -643,9 +857,134 @@ export async function ensureWorktree(localRepoPath: string, sourceBranch: string
     .catch(() => {})
   await execFileAsync('git', ['worktree', 'add', '--', worktreePath, `origin/${sourceBranch}`], { cwd: localRepoPath, timeout: GIT_TIMEOUT_MS })
   await writeFile(join(worktreePath, '.govard.local.yml'), govardWorktreeOverride(projectId, mrIid, keySuffix), 'utf-8')
+  await linkVendorIntoWorktree(localRepoPath, worktreePath)
+  await writeContainerVendorOverride(localRepoPath, worktreePath)
   return worktreePath
 }
 
+/**
+ * A vendor dir only counts as installed dependencies when the composer
+ * autoloader is a real file. Magento tracks `vendor/.htaccess`, so every
+ * worktree has a vendor/ stub — that stub must not pass for real deps, and
+ * must not block the container bind that provides them.
+ */
+export async function vendorHasAutoload(dir: string): Promise<boolean> {
+  try {
+    return (await stat(join(dir, 'vendor', 'autoload.php'))).isFile()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Share the primary checkout's `vendor/` (and `app/etc/env.php` when the
+ * auditor needs a database) into the review worktree via symlinks, so
+ * phpunit/static analysis run against real dependencies instead of falling
+ * back to static-only. Links point INTO the worktree only — the primary
+ * checkout is never written to — and `git worktree remove --force` deletes
+ * the links along with the worktree. Missing sources, or targets that
+ * already exist (e.g. Magento's tracked `vendor/.htaccess` stub), are
+ * skipped quietly: the review still runs, the auditor discloses it.
+ */
+export async function linkVendorIntoWorktree(localRepoPath: string, worktreePath: string): Promise<string[]> {
+  const linked: string[] = []
+  const candidates: Array<{ source: string; target: string; dir: boolean; needsAutoload: boolean }> = [
+    { source: join(localRepoPath, 'vendor'), target: join(worktreePath, 'vendor'), dir: true, needsAutoload: true },
+    { source: join(localRepoPath, 'app', 'etc', 'env.php'), target: join(worktreePath, 'app', 'etc', 'env.php'), dir: false, needsAutoload: false },
+  ]
+  let advertised = false
+  for (const { source, target, dir, needsAutoload } of candidates) {
+    let isDir = false
+    try {
+      isDir = (await stat(source)).isDirectory()
+      if (dir !== isDir) continue
+    } catch {
+      continue
+    }
+    if (needsAutoload && !(await vendorHasAutoload(localRepoPath))) continue
+    if ((await lstat(target).catch(() => undefined)) !== undefined) {
+      console.error(`maestro-orchestrator: link target exists, skipping ${target}`)
+      continue
+    }
+    try {
+      if (!advertised) {
+        const sha = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: localRepoPath, timeout: GIT_TIMEOUT_MS })
+          .then(({ stdout }) => stdout.trim()).catch(() => 'unknown')
+        console.error(`maestro-orchestrator: linking vendor from ${localRepoPath} @ ${sha} into ${worktreePath}`)
+        advertised = true
+      }
+      if (!dir) await mkdir(join(worktreePath, 'app', 'etc'), { recursive: true })
+      await symlink(source, target, dir ? 'dir' : 'file')
+      linked.push(target)
+    } catch (err) {
+      console.error(`maestro-orchestrator: failed to link ${source} into worktree:`, err)
+    }
+  }
+  if (!advertised) {
+    console.error(`maestro-orchestrator: no vendor/ in ${localRepoPath} — worktree ${worktreePath} runs without shared dependencies`)
+  }
+  return linked
+}
+
+/** Container path of the project root inside govard services. */
+const GOVARD_CONTAINER_WORKDIR = '/var/www/html'
+
+/**
+ * Render a compose override that bind-mounts the primary checkout's vendor/
+ * read-only into the php service. A host-side symlink alone dangles inside
+ * containers (absolute host path), so container tools (phpunit) need this
+ * bind to see real dependencies.
+ *
+ * The project mount (`.`) MUST be repeated first: govard merges overrides
+ * with MergeMap, which REPLACES lists instead of appending — an override
+ * carrying only the vendor bind would wipe `.:<workdir>` and leave the
+ * container docroot holding nothing but vendor/. Relative `.` resolves
+ * against the project root because govard passes --project-directory.
+ *
+ * Only the always-present `php` service is targeted: `php-debug` drops out
+ * of the rendered base when xdebug is off, and a volumes-only override
+ * entry would recreate it as a hollow service that fails compose validation.
+ */
+export function buildVendorOverrideYaml(vendorHostPath: string, envHostPath?: string, containerWorkDir: string = GOVARD_CONTAINER_WORKDIR): string {
+  const volumes = [
+    `.:${containerWorkDir}`,
+    `${vendorHostPath}:${containerWorkDir}/vendor:ro`,
+    ...(envHostPath !== undefined ? [`${envHostPath}:${containerWorkDir}/app/etc/env.php:ro`] : []),
+  ]
+  const service = `    volumes:\n${volumes.map((v) => `      - ${v}\n`).join('')}`
+  return `services:\n  php:\n${service}`
+}
+
+/**
+ * Drop the vendor bind override into the worktree (merged by govard via
+ * `.govard/docker-compose.override.yml`). Binds only when the primary
+ * checkout carries installed deps and the worktree does not — never shadow
+ * real deps with a possibly stale bind. Returns the written path, or
+ * undefined when skipped.
+ */
+export async function writeContainerVendorOverride(localRepoPath: string, worktreePath: string): Promise<string | undefined> {
+  const vendorHostPath = join(localRepoPath, 'vendor')
+  if (!(await vendorHasAutoload(localRepoPath))) return undefined
+  // Our own host-side symlink still needs the bind (it dangles in-container);
+  // only a real installed worktree vendor makes the bind redundant.
+  const wtLink = await lstat(join(worktreePath, 'vendor')).catch(() => undefined)
+  if (wtLink?.isSymbolicLink() !== true && await vendorHasAutoload(worktreePath)) return undefined
+  const overridePath = join(worktreePath, '.govard', 'docker-compose.override.yml')
+  await mkdir(join(worktreePath, '.govard'), { recursive: true })
+  // A linked env.php dangles in-container like the vendor symlink did — bind
+  // the real file over it when the primary checkout carries one.
+  const envHostPath = join(localRepoPath, 'app', 'etc', 'env.php')
+  let envBind: string | undefined
+  try {
+    if ((await stat(envHostPath)).isFile()) envBind = envHostPath
+  } catch {
+    envBind = undefined
+  }
+  await writeFile(overridePath, buildVendorOverrideYaml(vendorHostPath, envBind), 'utf-8')
+  console.error(`maestro-orchestrator: container vendor bind ${vendorHostPath} -> ${GOVARD_CONTAINER_WORKDIR}/vendor (ro) for ${worktreePath}`)
+  return overridePath
+}
+
 async function removeWorktree(worktreePath: string): Promise<void> {
   // Best-effort cleanup by design (a failure here must not block or fail the review that
   // already ran) — but a swallowed failure with zero visibility leaves an orphaned worktree
@@ -667,6 +1006,9 @@ export function apply(ctx: Context, config: Config): void {
   // effect without a plugin restart.
   let effectiveAgentTimeoutMs = config.agentTimeoutMs
   async function runReviewer(worktreePath: string | undefined, payload: ReviewRequest, effective: { gitlabBaseUrl: string; gitlabToken: string; botUsername: string }, reviewProfile?: ReviewSkillProfile, modelSelection?: ModelSelection, incrementalBlock?: string): Promise<ReviewOutcome> {
+    // MR base SHA feeds govard diff-scope runs; undefined degrades to the
+    // tool's fail-fast guidance instead of a wasted govard invocation.
+    const lintDefaultBase = await fetchMrBaseSha(effective.gitlabBaseUrl, effective.gitlabToken, payload.projectId, payload.mrIid)
     const primaryOptions = agentOptionsForModel(modelSelection ?? ctx.agentDefaultModel.currentSelection())
     const fallbackOptions: ModelSelection = { provider: primaryOptions.provider, model: primaryOptions.model }
     let lastHandle: AgentHandle | undefined
@@ -701,7 +1043,7 @@ export function apply(ctx: Context, config: Config): void {
               await agentCtx.plugin(ModuleCheckTool, { rootPath: worktreePath })
               await agentCtx.plugin(PhtmlEscapeScanTool, { rootPath: worktreePath })
               await agentCtx.plugin(ScopeSplitTool, { rootPath: worktreePath })
-              await agentCtx.plugin(GovardAuditLintTool, { rootPath: worktreePath })
+              await agentCtx.plugin(GovardAuditLintTool, { rootPath: worktreePath, defaultBase: lintDefaultBase, allowXdebug: true })
               await agentCtx.plugin(PerfLogStatsTool, { rootPath: worktreePath })
             }
           },
@@ -717,8 +1059,8 @@ export function apply(ctx: Context, config: Config): void {
           ? 'This is a diff-only review with no local checkout or Magento environment. Do not claim that tests, static analysis, or Magento runtime validation ran. '
           : `Call maestro_load_review_profile with {"profile":"${reviewProfile}"} before examining code. `
         let scopePrompt = payload.scope.kind === 'discussion'
-          ? `${profileInstruction}Review only the requested inline discussion ${payload.scope.discussionId} at ${payload.scope.path}:${payload.scope.line}. Do not review unrelated files or start a broad audit. Call gitlab_get_mr_diff, then call report_review_findings exactly once when done.`
-          : `${profileInstruction}Review this merge request (${payload.mode} mode). Call gitlab_list_own_review_threads and gitlab_get_mr_diff first, then call report_review_findings exactly once when done.`
+          ? buildReviewerScopePrompt({ scopeKind: 'discussion', discussionId: payload.scope.discussionId, path: payload.scope.path, line: payload.scope.line, profileInstruction })
+          : buildReviewerScopePrompt({ scopeKind: 'full', mode: payload.mode, profileInstruction })
         if (incrementalBlock !== undefined) scopePrompt = `${incrementalBlock}\n\n${scopePrompt}`
         handle.agent.followup(createUserMessage({
           content: [{ type: 'text', text: scopePrompt }],
@@ -759,7 +1101,7 @@ export function apply(ctx: Context, config: Config): void {
             failures.push(`${locator}: ${err instanceof Error ? err.message : String(err)}`)
           }
         }
-        return { summary: `${postedNew} new inline comment(s), ${postedReplies} thread(s) updated.`, failures }
+        return { summary: `${postedNew} new inline comment(s), ${postedReplies} thread(s) updated.`, failures, severityCounts: countFindingSeverities(capturedFindings) }
       } finally {
         await handle.dispose()
       }
@@ -792,7 +1134,7 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
-  async function runAuditor(worktreePath: string, payload: ReviewRequest, effective: { gitlabBaseUrl: string; gitlabToken: string; botUsername: string }, modelSelection?: ModelSelection): Promise<string> {
+  async function runAuditor(worktreePath: string, payload: ReviewRequest, effective: { gitlabBaseUrl: string; gitlabToken: string; botUsername: string }, modelSelection?: ModelSelection, opts?: { staticOnly?: boolean }): Promise<string> {
     let handle: AgentHandle
     const agentOptions = agentOptionsForModel(modelSelection ?? ctx.agentDefaultModel.currentSelection())
     try {
@@ -819,10 +1161,10 @@ export function apply(ctx: Context, config: Config): void {
     }
     ctx.sessionTitle.rename(handle.agent.session, `Maestro Auditor — MR !${payload.mrIid} (${payload.projectPath})`)
     try {
-      const prompt = 'Audit this merge request\'s performance: bring up the environment, run the test suite, look for regressions, then write a Markdown report and tear the environment down.'
+      const prompt = buildAuditorPrompt({ staticOnly: opts?.staticOnly === true })
       handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: prompt }], source: { kind: 'user' } }))
       await whenIdleWithTimeout(handle, effectiveAgentTimeoutMs)
-      const output = finalAssistantOutput(handle.agent.session.events) ?? []
+      const output = auditorOutputFromSession(handle.agent.session)
       const text = output.map(block => ('text' in block ? block.text : '')).join('')
       return `## Maestro Performance Audit\n\n${text}`
     } finally {
@@ -830,8 +1172,9 @@ export function apply(ctx: Context, config: Config): void {
     }
   }
 
-  ctx.on('maestro/review-request', (payload) => {
-    void (async () => {
+  async function runReview(payload: ReviewRequest): Promise<ReviewResult> {
+    const t0 = Date.now()
+    try {
       const userConfig = await loadUserConfig()
       const effective = {
         gitlabBaseUrl: userConfig.gitlabBaseUrl ?? config.gitlabBaseUrl,
@@ -849,16 +1192,37 @@ export function apply(ctx: Context, config: Config): void {
         })
       }
       const mapping = effective.projectMappings.find(m => m.projectPath === payload.projectPath)
+      // CI-deep (spec §3): unmapped deep review with CI env + head SHA skips
+      // both the decline and the diff-only fallback and runs the clone branch
+      // below, which shares the mapped path's completion tail.
+      const ciDeep = mapping === undefined && payload.mode === 'deep' && shouldCiDeepReview(payload)
+      // CI quick-with-profile: unmapped quick + non-generic profile + CI env
+      // skips the diff-only fallback and joins the clone branch below, which
+      // runs reviewer-only (quick never audits).
+      const ciQuickProfile = mapping === undefined && shouldCiQuickProfileReview(payload)
       // Unmapped reviewer assignments remain no-ops. Only an explicit mention
       // may opt into the intentionally limited, diff-only fallback below.
-      if (mapping === undefined && payload.trigger !== 'mention') return
+      if (mapping === undefined && payload.trigger !== 'mention') {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
+      const triggers = resolveReviewTriggers(userConfig, mapping)
+      // Gated-off auto-triggers stay fully silent: no history, no signals, no comment.
+      if (payload.trigger === 'reviewer-assignment' && !triggers.onAssign) {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
+      if (payload.trigger === 'push' && !triggers.onPush) {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
       // A push only re-reviews an MR that already has a completed review;
       // otherwise every newly opened MR would be reviewed twice.
-      if (payload.trigger === 'push' && !(await hasCompletedReview(payload.projectId, payload.mrIid))) return
+      if (payload.trigger === 'push' && !(await hasCompletedReview(payload.projectId, payload.mrIid))) {
+        return { ok: true, failures: [], durationMs: Date.now() - t0 }
+      }
       const { gitlabToken } = effective
       if (gitlabToken === undefined) {
-        console.error(`maestro-orchestrator: MR !${String(payload.mrIid)} for project ${payload.projectPath} has no GitLab token — set one in Maestro Settings or MAESTRO_GITLAB_TOKEN`)
-        return
+        const message = `MR !${String(payload.mrIid)} for project ${payload.projectPath} has no GitLab token — set one in Maestro Settings or MAESTRO_GITLAB_TOKEN`
+        console.error(`maestro-orchestrator: ${message}`)
+        return { ok: false, failures: [message], durationMs: Date.now() - t0 }
       }
       const resolved = { ...effective, gitlabToken }
       const historyId = `${payload.projectId}-${payload.mrIid}-${Date.now()}`
@@ -889,7 +1253,7 @@ export function apply(ctx: Context, config: Config): void {
       const fallbackSelection: ModelSelection = (ctx.get?.('agentDefaultModel') as { currentSelection(): ModelSelection } | undefined)?.currentSelection()
         ?? (ctx as unknown as { agentDefaultModel?: { currentSelection(): ModelSelection } }).agentDefaultModel?.currentSelection()
         ?? { provider: 'fallback', model: 'fallback' }
-      const reviewModelSelection = resolveReviewModel(userConfig, mapping, fallbackSelection)
+      const reviewModelSelection = resolveReviewModel(userConfig, mapping, fallbackSelection, config.reviewModel)
       // Opt-in Telegram digest; a delivery failure is logged and dropped.
       const reviewStartMsOuter = Date.now()
       const notifyTelegram = (
@@ -947,7 +1311,7 @@ export function apply(ctx: Context, config: Config): void {
           `${resolved.gitlabBaseUrl}/api/v4/projects/${payload.projectId}/merge_requests/${payload.mrIid}/notes`,
           {
             method: 'POST',
-            headers: { 'PRIVATE-TOKEN': resolved.gitlabToken, 'Content-Type': 'application/json' },
+            headers: { ...gitlabAuthHeaders(resolved.gitlabToken), 'Content-Type': 'application/json' },
             body: JSON.stringify({ body }),
           },
         )
@@ -958,23 +1322,25 @@ export function apply(ctx: Context, config: Config): void {
           `${resolved.gitlabBaseUrl}/api/v4/projects/${payload.projectId}/merge_requests/${payload.mrIid}/discussions/${encodeURIComponent(discussionId)}/notes`,
           {
             method: 'POST',
-            headers: { 'PRIVATE-TOKEN': resolved.gitlabToken, 'Content-Type': 'application/json' },
+            headers: { ...gitlabAuthHeaders(resolved.gitlabToken), 'Content-Type': 'application/json' },
             body: JSON.stringify({ body }),
           },
         )
         if (!response.ok) throw new Error(`GitLab API error ${response.status}: ${await response.text()}`)
       }
       try {
-        if (mapping === undefined) {
-          if (payload.mode === 'deep') {
+        if (mapping === undefined && !ciDeep && !ciQuickProfile) {
+          // CI-deep (spec §3) skips the decline and falls through to the clone
+          // branch below; every other unmapped deep review still declines here.
+          if (payload.mode === 'deep' && !shouldCiDeepReview(payload)) {
             await declineUnmappedDeepReview(payload, { postComment, replyToDiscussion, writeFailedReport, gitlabBaseUrl: resolved.gitlabBaseUrl } as unknown as ReviewCommentDeps)
             await recordReviewFinish(historyId, { status: 'completed', summary: 'Deep review declined (unmapped project)' })
             notifyTelegram('completed', 'Deep review declined (unmapped project)')
             await signals?.finish('completed')
-            return
+            return { ok: true, summary: 'Deep review declined (unmapped project)', failures: [], durationMs: Date.now() - t0 }
           }
           const diffBody = await runDiffOnlyReview(payload, {
-            runReviewer: (p) => runReviewer(undefined, p, resolved, undefined, reviewModelSelection, incrementalBlock),
+            runReviewer: (p) => runReviewer(undefined, p, resolved, payload.reviewProfile, reviewModelSelection, incrementalBlock),
             postComment,
             replyToDiscussion,
             writeFailedReport,
@@ -983,9 +1349,47 @@ export function apply(ctx: Context, config: Config): void {
           await recordReviewFinish(historyId, { status: 'completed', summary: summarize(diffBody) })
           notifyTelegram('completed', summarize(diffBody))
           await signals?.finish('completed')
-          return
+          return { ok: true, summary: summarize(diffBody), failures: [], durationMs: Date.now() - t0 }
         }
         let fullBody: string
+        if (ciDeep || ciQuickProfile) {
+          // CI-deep (mapping is always undefined here — the unmapped block above
+          // returned for every other case): clone the source at the head SHA,
+          // map it in memory, and reuse the mapped machinery reviewer-only.
+          // CI quick-with-profile joins the same branch; runReviewAndAudit skips
+          // the auditor for quick (shouldAudit), so it stays reviewer-only.
+          // No govard/vendor linking (ciEnsureWorktree is plain fetch + worktree).
+          const ciHost = process.env.GITLAB_HOST?.trim() || new URL(resolved.gitlabBaseUrl).hostname
+          const cloneDir = join('/tmp', `maestro-ci-src-${payload.projectId}-${payload.mrIid}`)
+          await cloneSourceRepo({ fetcher: fetch, run: defaultRun, host: ciHost, projectId: payload.projectId, sourceBranch: payload.sourceBranch, headSha: payload.headSha as string, token: resolved.gitlabToken, dir: cloneDir })
+          try {
+            const ciEnsureWorktree = async (repoPath: string, branch: string, pid: number, iid: number, suffix?: string): Promise<string> => {
+              assertSafeBranchName(branch)
+              const wt = join('/tmp', `maestro-mr-${pid}-${iid}${suffix === undefined ? '' : `-${suffix}`}`)
+              await defaultRun('git', ['fetch', '--depth', '50', 'origin', branch], repoPath)
+              await defaultRun('git', ['worktree', 'remove', '--force', wt], repoPath).catch(() => {})
+              await defaultRun('git', ['worktree', 'add', '--detach', '--', wt, payload.headSha as string], repoPath)
+              return wt
+            }
+            fullBody = await runReviewAndAudit(payload, {
+              localRepoPath: cloneDir,
+              ensureWorktree: ciEnsureWorktree,
+              removeWorktree,
+              runReviewer: (worktreePath, p) => runReviewer(worktreePath, p, resolved, payload.reviewProfile ?? 'generic', reviewModelSelection, incrementalBlock),
+              runAuditor: withAuditorDegrade((worktreePath, p) => runAuditor(worktreePath, p, resolved, reviewModelSelection, { staticOnly: true })),
+              postComment,
+              replyToDiscussion,
+              writeFailedReport,
+              gitlabBaseUrl: resolved.gitlabBaseUrl,
+              reviewProfile: payload.reviewProfile ?? 'generic',
+            } as unknown as ReviewAndAuditDeps)
+          } finally {
+            await defaultRun('rm', ['-rf', cloneDir]).catch(() => {})
+          }
+        } else {
+        // Unreachable when mapping is undefined: the unmapped block returned
+        // for every non-CI-deep case, and ciDeep took the branch above.
+        if (mapping === undefined) throw new Error('unreachable: unmapped review without CI-deep decision')
         try {
           fullBody = await runReviewAndAudit(payload, {
             localRepoPath: mapping.localRepoPath,
@@ -1003,7 +1407,7 @@ export function apply(ctx: Context, config: Config): void {
           const isBranchNotFound = (err as { code?: string })?.code === 'BRANCH_NOT_FOUND' || isBranchNotFoundError(err)
           if (isBranchNotFound) {
             const diffBody = await runDiffOnlyReview(payload, {
-              runReviewer: (p) => runReviewer(undefined, p, resolved, undefined, reviewModelSelection, incrementalBlock),
+              runReviewer: (p) => runReviewer(undefined, p, resolved, payload.reviewProfile, reviewModelSelection, incrementalBlock),
               postComment,
               replyToDiscussion,
               writeFailedReport,
@@ -1014,25 +1418,33 @@ export function apply(ctx: Context, config: Config): void {
             await recordReviewFinish(historyId, { status: 'completed', summary: branchNote })
             notifyTelegram('completed', branchNote)
             await signals?.finish('completed')
-            return
+            return { ok: true, summary: branchNote, failures: [], durationMs: Date.now() - t0 }
           }
           throw err
         }
+        }
         await recordReviewFinish(historyId, { status: 'completed', summary: summarize(fullBody) })
         notifyTelegram('completed', summarize(fullBody))
         await signals?.finish('completed')
+        return { ok: true, summary: summarize(fullBody), failures: [], durationMs: Date.now() - t0 }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
         await recordReviewFinish(historyId, { status: 'failed', error: message }).catch(() => {})
         notifyTelegram('failed', message)
         await signals?.finish('failed')
-        throw err
+        return { ok: false, summary: undefined, failures: [message], durationMs: Date.now() - t0 }
       }
-    })().catch((err: unknown) => {
+    } catch (err) {
       // Worktree creation, agent creation, and fallback delivery all run from
-      // an event callback, so surface failures rather than leaking a rejected
-      // fire-and-forget Promise.
+      // this function — surface failures as a result instead of an unhandled
+      // rejection, so both the fire-and-forget webhook path and an awaiting
+      // CI caller observe the same outcome.
+      const message = err instanceof Error ? err.message : String(err)
       console.error(`maestro-orchestrator: review run failed for MR !${String(payload.mrIid)}:`, err)
-    })
-  })
+      return { ok: false, summary: undefined, failures: [message], durationMs: Date.now() - t0 }
+    }
+  }
+
+  ctx.on('maestro/review-request', (payload) => { void runReview(payload) })
+  ctx.provide('reviewRunner', runReview)
 }