@ddtcorex/dsh-maestro-review 0.3.1 → 0.4.0

package/src/host/govard-audit-lint-tool.ts

@@ -7,7 +7,39 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 
 export const name='maestro-govard-audit-lint-tool'
 export const inject=['tools']
-export const Config:z<{rootPath?:string, timeoutMs?:number}> = z.object({rootPath:z.string(), timeoutMs:z.number()})
+export const Config:z<{rootPath?:string, timeoutMs?:number, defaultBase?:string, allowXdebug?:boolean}> = z.object({rootPath:z.string(), timeoutMs:z.number(), defaultBase:z.string(), allowXdebug:z.boolean()})
+
+export interface AuditLintOptions {
+  checks?: string[]
+  mode?: string
+  scope?: string
+  base?: string
+  phpVersions?: string[]
+  noLintResultCache?: boolean
+  timeout?: string
+  lintProvider?: string
+  allowXdebug?: boolean
+}
+
+/** Explicit call base wins, then the review-wired default (MR base_sha). */
+export function resolveLintBase(argsBase: string | undefined, defaultBase: string | undefined): string | undefined {
+  return argsBase ?? defaultBase
+}
+
+export function buildAuditCliArgs(a: AuditLintOptions): string[] {
+  const checks = a.checks && a.checks.length ? a.checks.join(',') : 'lint'
+  const mode = a.mode ?? 'auto'
+  const timeout = a.timeout ?? 'auto'
+  const lintProvider = a.lintProvider ?? 'govard'
+  const cliArgs=['audit','run','--checks',checks,'--format','json','--mode',mode,'--timeout',timeout,'--lint-provider',lintProvider]
+  if(a.scope) cliArgs.push('--scope', a.scope)
+  const base = resolveLintBase(a.base, undefined)
+  if(base) cliArgs.push('--base', base)
+  if(a.phpVersions && a.phpVersions.length) cliArgs.push('--php', a.phpVersions.join(','))
+  if(a.noLintResultCache) cliArgs.push('--no-lint-result-cache')
+  if(a.allowXdebug) cliArgs.push('--allow-xdebug')
+  return cliArgs
+}
 
 interface SC{agent?:{session?:{header?:{cwd?:string}}}}
 function workspaceRootFor(c:string|undefined, e:unknown):string{
@@ -38,7 +70,98 @@ async function isInsideRoot(r:string,t:string):Promise<boolean>{
   }
 }
 export function cleanJson(raw:string):string{
-  return raw.replace(/\n\s*ERROR audit run.*$/s, '').replace(/\s{2,}ERROR audit run.*$/s, '').trimEnd()
+  // pterm pads the level name: "  ERROR   audit run ..." (multi-space).
+  return raw.replace(/\n\s*ERROR\s+audit run.*$/s, '').replace(/\s{2,}ERROR\s+audit run.*$/s, '').trimEnd()
+}
+
+interface LintViolationLike { path?: string; line?: number; rule?: string; message?: string }
+
+interface LintResultLike {
+  ok: boolean
+  exitCode?: number
+  lint?: {
+    phpcs?: { violations?: LintViolationLike[] }
+    phpstan?: { errors?: LintViolationLike[] }
+    pubMediaGuard?: { violations?: LintViolationLike[] }
+  }
+  summary?: { findingCount?: number }
+  diagnostics?: string
+}
+
+/**
+ * One-line-plus render for the agent: a bare "audit lint failed" hides the
+ * violations the reviewer needs, so carry counts plus the top findings.
+ */
+export interface CollectedLintFindings {
+  phpcsViolations: Array<{ path?: string; line?: number; column?: number; rule?: string; message?: string; severity?: string }>
+  phpstanErrors: Array<{ path?: string; line?: number; message?: string }>
+  pubMediaViolations: unknown[]
+  compat: Array<{ tool?: string; path?: string; line?: number; rule?: string; message?: string }>
+  total: number
+}
+
+/**
+ * Collect findings across govard audit JSON shapes. The live envelope nests
+ * them at results[].evidence.php_results[].findings (older callers used a
+ * top-level findings array or evidence.php_results) — and non-phpcs/phpstan
+ * tools (e.g. M2-LINT-COMPAT internal errors) go to the compat bucket
+ * instead of being silently dropped from counts.
+ */
+export function collectLintFindings(parsed: unknown): CollectedLintFindings {
+  const p = (parsed ?? {}) as Record<string, any>
+  const lists: unknown[][] = []
+  if (Array.isArray(p.findings)) lists.push(p.findings)
+  const ev = p.evidence as Record<string, any> | undefined
+  if (Array.isArray(ev?.php_results)) lists.push(...ev.php_results.map((r: any) => r?.findings).filter(Array.isArray))
+  if (Array.isArray(p.php_results)) lists.push(...p.php_results.map((r: any) => r?.findings).filter(Array.isArray))
+  // Live shape (govard audit run): jobs[].evidence.php_results[].findings.
+  // Older shapes (results[], bare evidence) kept for backward compatibility.
+  for (const key of ['jobs', 'results'] as const) {
+    if (!Array.isArray(p[key])) continue
+    for (const r of p[key] as Array<Record<string, any>>) {
+      const e = r?.evidence as Record<string, any> | undefined
+      const pr = e?.php_results ?? r?.php_results
+      if (Array.isArray(pr)) lists.push(...pr.map((x: any) => x?.findings).filter(Array.isArray))
+      if (Array.isArray(r?.findings)) lists.push(r.findings)
+    }
+  }
+  const out: CollectedLintFindings = { phpcsViolations: [], phpstanErrors: [], pubMediaViolations: [], compat: [], total: 0 }
+  // DSH tool output must be lossless JSON: drop undefined fields, the
+  // runtime rejects values that do not survive a JSON round-trip.
+  const compact = (entry: Record<string, unknown>): Record<string, unknown> => {
+    const kept: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(entry)) if (v !== undefined) kept[k] = v
+    return kept
+  }
+  for (const list of lists) {
+    for (const f of list as Array<Record<string, any>>) {
+      if (f?.tool === 'phpstan') out.phpstanErrors.push(compact({ path: f.path, line: f.line, message: f.message }) as CollectedLintFindings['phpstanErrors'][number])
+      else if (f?.tool === 'phpcs') {
+        if (f.path?.includes('pub/media') || f.rule?.includes('PubMedia')) out.pubMediaViolations.push(f)
+        else out.phpcsViolations.push(compact({ path: f.path, line: f.line, column: f.column, rule: f.rule, message: f.message, severity: f.severity }) as CollectedLintFindings['phpcsViolations'][number])
+      } else if (f && typeof f === 'object') {
+        out.compat.push(compact({ tool: f.tool, path: f.path, line: f.line, rule: f.rule, message: f.message }) as CollectedLintFindings['compat'][number])
+      }
+    }
+  }
+  out.total = out.phpcsViolations.length + out.phpstanErrors.length + out.pubMediaViolations.length + out.compat.length
+  return out
+}
+
+export function lintResultText(v: LintResultLike): string {
+  if (v.ok) return 'audit lint passed'
+  const phpcs = v.lint?.phpcs?.violations ?? []
+  const phpstan = v.lint?.phpstan?.errors ?? []
+  const pubMedia = v.lint?.pubMediaGuard?.violations ?? []
+  const compat = (v.lint as Record<string, any> | undefined)?.compat?.findings ?? []
+  const total = v.summary?.findingCount ?? phpcs.length + phpstan.length + pubMedia.length + compat.length
+  const bits: string[] = [`audit lint failed — ${total} finding(s) (phpcs ${phpcs.length}, phpstan ${phpstan.length}, pubMedia ${pubMedia.length}, compat ${compat.length})`]
+  const top = [...phpcs.map(x => ({ ...x, tool: 'phpcs' })), ...phpstan.map(x => ({ ...x, tool: 'phpstan' })), ...pubMedia.map(x => ({ ...x, tool: 'pubMedia' })), ...compat.map((x: Record<string, any>) => ({ ...x, tool: x.tool ?? 'compat' }))].slice(0, 5)
+  for (const f of top) bits.push(`- [${f.tool}] ${f.path ?? (f.message ?? '?').toString().slice(0, 120)}${f.path !== undefined ? `:${f.line ?? '?'}` : ''}${f.rule !== undefined ? ` ${f.rule}` : ''}`)
+  if (v.exitCode !== undefined) bits.push(`exit ${v.exitCode}`)
+  const diag = (v.diagnostics ?? '').split('\n')[0]?.trim()
+  if (total === 0 && diag !== '' && diag !== undefined) bits.push(diag.slice(0, 200))
+  return bits.join('\n')
 }
 // Govard 1.67 auto timeout: 90s-30m framework-aware (15m floor for wordpress/magento2 → 22.5m auto)
 // Keep kill timeout above the largest auto value so the outer watchdog doesn't cancel a valid auto run.
@@ -57,12 +180,16 @@ function run(cmd:string, args:string[], cwd:string, timeoutMs:number):Promise<{c
   })
 }
 
-export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number}={}):void{
+export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number, defaultBase?:string, allowXdebug?:boolean}={}):void{
   const configuredRoot=config.rootPath
   const defaultTimeout=config.timeoutMs ?? DEFAULT_TIMEOUT
+  const defaultBase=config.defaultBase
+  // Review worktrees disable xdebug via .govard.local.yml, but govard's lint
+  // guard probes the base .govard.yml only — so the mount opts out explicitly.
+  const allowXdebug=config.allowXdebug ?? false
   ctx.effect(()=>ctx.tools.register(defineTool({
     name:'govard_audit_lint',
-    description:'Run govard audit --checks lint --format json and return structured phpcs/phpstan results. Use before hand-parsing text. Govard 1.67+ uses --timeout auto (framework-aware 90s-30m, 22.5m for wordpress/magento2) by default.',
+    description:'Run govard audit --checks lint --format json and return structured phpcs/phpstan results. Use before hand-parsing text. Govard 1.67+ uses --timeout auto (framework-aware 90s-30m, 22.5m for wordpress/magento2) by default. scope "diff" requires a base ref: pass base, or rely on the wired defaultBase (MR base_sha) when present.',
     parameters:{
       worktreePath:{type:'string'},
       checks:{type:'array', items:{type:'string'}},
@@ -93,7 +220,7 @@ export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number}=
           runId:{type:'string'},
         }
       },
-      render:(_a,v:{ok:boolean})=>[{type:'text', text: v.ok? 'audit lint passed':'audit lint failed'}],
+      render:(_a,v:LintResultLike)=>[{type:'text', text: lintResultText(v)}],
     },
     async execute(args, exec){
       const rawPath=(args as {worktreePath?:string}).worktreePath
@@ -104,20 +231,13 @@ export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number}=
       const timeoutMs=(args as {timeoutMs?:number}).timeoutMs ?? defaultTimeout
       if(timeoutMs<5000 || timeoutMs>1_800_000) return {text:'timeoutMs out of range 5000-1800000 (5s-30m). Use --timeout auto for framework-aware estimation.', truncated:false} as never
 
-      const a = args as {checks?:string[]; mode?:string; scope?:string; base?:string; phpVersions?:string[]; noLintResultCache?:boolean; timeout?:string; lintProvider?:string}
-      const checks = a.checks && a.checks.length ? a.checks.join(',') : 'lint'
-      const mode = a.mode ?? 'auto'
+      const a = args as {checks?:string[]; mode?:string; scope?:string; base?:string; phpVersions?:string[]; noLintResultCache?:boolean; timeout?:string; lintProvider?:string; allowXdebug?:boolean}
       const scope = a.scope
-      const base = a.base
-      const phpVersionsArg = a.phpVersions
-      const noLintResultCache = a.noLintResultCache
-      const timeout = a.timeout ?? 'auto'
-      const lintProvider = a.lintProvider ?? 'govard'
-      const cliArgs=['audit','run','--checks',checks,'--format','json','--mode',mode,'--timeout',timeout,'--lint-provider',lintProvider]
-      if(scope) cliArgs.push('--scope', scope)
-      if(base) cliArgs.push('--base', base)
-      if(phpVersionsArg && phpVersionsArg.length) cliArgs.push('--php', phpVersionsArg.join(','))
-      if(noLintResultCache) cliArgs.push('--no-lint-result-cache')
+      const base = resolveLintBase(a.base, defaultBase)
+      if (scope === 'diff' && base === undefined) {
+        return {text:'scope "diff" requires a base ref (govard --base): pass base explicitly (e.g. origin/master or the MR base_sha) or mount this tool with defaultBase.', truncated:false} as never
+      }
+      const cliArgs = buildAuditCliArgs({ ...a, base, allowXdebug: a.allowXdebug ?? allowXdebug })
       const result=await run('govard', cliArgs, worktreePath, timeoutMs)
       if(result.timedOut){
         return {ok:false, exitCode: result.code ?? 124, timedOut:true, worktreePath, lint:{phpcs:{violations:[]}, phpstan:{errors:[]}, pubMediaGuard:{violations:[]}}, summary:{status:null, phpVersions:[], matrixComplete:false, findingCount:0, truncated:false}, rawJson:{}, errors:[{code:'timeout', message:`timed out after ${timeoutMs}ms` }], diagnostics:result.stderr.slice(0,4000)} as never
@@ -139,20 +259,13 @@ export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number}=
       if(!parsed){
         return {ok:false, exitCode: result.code ?? 1, timedOut:false, worktreePath, lint:{phpcs:{violations:[]}, phpstan:{errors:[]}, pubMediaGuard:{violations:[]}}, summary:{status:null, phpVersions:[], matrixComplete:false, findingCount:0, truncated:false}, rawJson:{}, errors:[{code:'parse_error', message:'stdout not JSON'}], diagnostics:(cleaned+result.stderr).slice(0,4000)} as never
       }
-      const findings:Array<any>=parsed.findings ?? parsed.evidence?.php_results?.flatMap((r:any)=>r.findings) ?? []
-      const phpcsViolations:any[]=[]
-      const phpstanErrors:any[]=[]
-      const pubMediaViolations:any[]=[]
-      for(const f of findings){
-        if(f.tool==='phpstan') phpstanErrors.push({path:f.path, line:f.line, message:f.message})
-        else if(f.tool==='phpcs'){
-          if(f.path?.includes('pub/media') || f.rule?.includes('PubMedia')) pubMediaViolations.push(f)
-          else phpcsViolations.push({path:f.path, line:f.line, column:f.column, rule:f.rule, message:f.message, severity:f.severity})
-        }
-      }
+      const collected = collectLintFindings(parsed)
+      const phpcsViolations = collected.phpcsViolations
+      const phpstanErrors = collected.phpstanErrors
+      const pubMediaViolations = collected.pubMediaViolations
       const status=parsed.status ?? (result.code===0?'passed':'failed')
       const phpVersions=parsed.php_versions ?? parsed.phpVersions ?? []
-      const findingCount=findings.length
+      const findingCount=collected.total
       const sessionId = parsed.session_id ?? parsed.sessionId ?? undefined
       const runId = parsed.run_id ?? parsed.runId ?? undefined
       return {
@@ -164,7 +277,7 @@ export function apply(ctx:Context, config:{rootPath?:string, timeoutMs?:number}=
         ...(runId ? { runId: String(runId) } : {}),
         rawJson: parsed as Record<string, unknown>,
         summary:{status, phpVersions, matrixComplete:true, findingCount, truncated: findingCount>100},
-        lint:{phpcs:{violations:phpcsViolations}, phpstan:{errors:phpstanErrors}, pubMediaGuard:{violations:pubMediaViolations}},
+        lint:{phpcs:{violations:phpcsViolations}, phpstan:{errors:phpstanErrors}, pubMediaGuard:{violations:pubMediaViolations}, compat:{findings:collected.compat}},
         errors:[],
         diagnostics: result.stderr.slice(0,4000),
       } as never

package/src/host/govard-tool.ts

@@ -82,7 +82,7 @@ export function apply(ctx: Context, config: Config): void {
     name: 'govard_shell',
     description: 'Run one non-interactive command inside the Govard-managed container (e.g. a test suite) and return its output.',
     parameters: {
-      command: { type: 'string', required: true, description: 'Shell command to run inside the container, e.g. "vendor/bin/phpunit".' },
+      command: { type: 'string', required: true, description: 'Shell command to run inside the container. PHPUnit in a Magento root: always scope it — "vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist --filter <Module>" or "vendor/bin/phpunit --no-coverage --bootstrap dev/tests/unit/framework/bootstrap.php app/code/<Vendor>/<Module>/Test/Unit". The root ships no phpunit.xml so the bare binary prints usage and exits 1; never run the full suite bare (core fixture conflicts), and capture status via ${PIPESTATUS[0]} when piping through tail.' },
     },
     output: {
       schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },

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,7 +29,7 @@ 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 { ReviewFinding, FindingSeverity } from './review-findings-tool.js'
 import type { ReviewRequest } from './events.js'
 import { loadUserConfig, type MaestroUserConfig, type ReviewModelSelection } from './config-store.js'
 import { hasCompletedReview, lastCompletedReview, pruneHistory, recordReviewFinish, recordReviewStart } from './review-history.js'
@@ -58,6 +58,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,7 +128,7 @@ 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
@@ -97,6 +153,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(' · ')}`
       })()
@@ -223,6 +285,7 @@ export const Config: z<Config> = z.object({
 export interface ReviewOutcome {
   summary: string
   failures: string[]
+  severityCounts?: Partial<Record<FindingSeverity, number>>
 }
 
 /**
@@ -374,10 +437,12 @@ export async function postReviewFindings(findings: ReviewFinding[], config: Gitl
   const headers = { 'PRIVATE-TOKEN': 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 +460,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,6 +518,33 @@ 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. */
 export async function runReviewAndAudit(payload: ReviewRequest, deps: ReviewAndAuditDeps): Promise<string> {
   assertSafeId(payload.projectId, 'projectId')
@@ -471,7 +563,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 +580,7 @@ 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 },
             })
           : `## 🤖 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)
@@ -619,7 +711,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: { 'PRIVATE-TOKEN': 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 +762,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 +911,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 +948,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 +964,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 +1006,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()
       }
@@ -822,7 +1069,7 @@ export function apply(ctx: Context, config: Config): void {
       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.'
       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 {