iterate-plugin 3.5.7 → 3.7.0

package/src/tools/prune.ts

@@ -21,16 +21,18 @@
  * Security model:
  *   - Only operates under the resolved project `.iterate/` directory.
  *   - dryRun=true by default — the caller must explicitly opt into deletion.
- *   - Each deletion is logged to the decision log (when not dry-run).
+ *   - Each non-dry-run appends ONE aggregate summary entry to the decision
+ *     log (counts per artifact class) — not one log line per deleted file.
  */
 
-import { existsSync, readdirSync, rmSync, unlinkSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, rmSync, unlinkSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { writeTextAtomic, writeJsonAtomic } from '../atomic-fs.ts'
-import { readDecisionEntries, appendDecisionEntry, acquireLogLock, invalidateLogCountCache } from './decision-log.ts'
+import { withProjectLock } from '../file-lock.ts'
+import { readDecisionEntries, appendDecisionEntry, acquireLogLockChecked, invalidateLogCountCache } from './decision-log.ts'
 import { readRegistry, removeRecord, recomputeRoundCounts } from './fix.ts'
 import { readExperienceBank, writeExperienceBank } from './experience-store.ts'
 import { readDefenseEvents, writeDefenseEvents } from './defense-store.ts'
@@ -97,12 +99,20 @@ export function sweepExperienceBank(bank: ExperienceBank, cap: number): { bank:
   const size = Number.isFinite(cap) && (cap as number) >= 0 ? Math.floor(cap) : MAX_EXPERIENCE_ENTRIES
   const total = bank.entries.length
   if (total <= size) return { bank, removed: 0 }
-  const kept = [...bank.entries]
-    .sort((a, b) => (b.timestamp ?? '').localeCompare(a.timestamp ?? ''))
-    .slice(0, size)
-  // Preserve the original (insertion) order of the surviving entries.
-  const keptIds = new Set(kept.map((e) => e.id))
-  const ordered = bank.entries.filter((e) => keptIds.has(e.id))
+  // Keep by POSITION, not by id: a Set of kept ids lets duplicate ids (a
+  // hand-edited or double-written bank) defeat the cap — every original entry
+  // sharing a kept id would survive, so `removed` stayed 0 and the cap never
+  // applied. Rank positions newest-first (ties fall back to the original index
+  // so equal timestamps keep insertion order, as before), keep the first `size`
+  // positions, then re-emit the survivors in insertion order.
+  const ranked = bank.entries.map((_, i) => i)
+  ranked.sort((a, b) => {
+    const ta = bank.entries[a]?.timestamp ?? ''
+    const tb = bank.entries[b]?.timestamp ?? ''
+    return tb.localeCompare(ta) || a - b
+  })
+  const keep = new Set(ranked.slice(0, size))
+  const ordered = bank.entries.filter((_, i) => keep.has(i))
   return {
     bank: { ...bank, entries: ordered, lastUpdated: new Date().toISOString() },
     removed: total - ordered.length,
@@ -160,6 +170,9 @@ export function inspectPrune(
   emptyRounds: number[]
   totalLogEntries: number
   registryRounds: number
+  /** Non-null when the fix registry file is PRESENT but unreadable/corrupt —
+   *  stale-backup deletion must then be refused (see `executePrune`). */
+  registryError: string | null
   totalExperiences: number
   experienceOversize: number
   totalDefenseEvents: number
@@ -187,6 +200,26 @@ export function inspectPrune(
   }
 
   // 3. Stale fix backups: .bak files whose fix-id prefix is not in the registry.
+  //
+  // `readRegistry` returns an EMPTY registry for BOTH "file absent" and "file
+  // present but corrupt" — and for the corrupt case an empty active-id set
+  // would classify EVERY backup stale, so a single dryRun:false prune would
+  // delete the entire rollback safety net. Read the registry file directly to
+  // distinguish the two: absent ⇒ backups are orphaned (stale, delete as
+  // before); present-but-unreadable ⇒ set `registryError`, classify nothing,
+  // and let `executePrune`/the render surface the refusal.
+  const registryFile = fixRegistryPath(projectRoot)
+  let registryError: string | null = null
+  if (existsSync(registryFile)) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(registryFile, 'utf-8'))
+      if (!parsed || typeof parsed !== 'object' || !Array.isArray((parsed as { rounds?: unknown }).rounds)) {
+        registryError = `refusing to delete fix backups: fix registry is present but unreadable (invalid shape): ${registryFile}`
+      }
+    } catch (err) {
+      registryError = `refusing to delete fix backups: fix registry is present but unreadable: ${String(err)} (${registryFile})`
+    }
+  }
   const registry = readRegistry(projectRoot)
   const activeIds = new Set<string>()
   for (const r of registry.rounds) {
@@ -204,14 +237,16 @@ export function inspectPrune(
   } catch {
     fixEntries = []
   }
-  for (const entry of fixEntries) {
-    if (!entry.endsWith('.bak')) continue
-    // Extract the fix-id prefix (up to the first underscore after the id).
-    // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
-    const match = entry.match(/^(fix-[a-z0-9]+)_/)
-    const id = match?.[1]
-    if (id && !activeIds.has(id)) {
-      staleBackups.push(entry)
+  if (registryError === null) {
+    for (const entry of fixEntries) {
+      if (!entry.endsWith('.bak')) continue
+      // Extract the fix-id prefix (up to the first underscore after the id).
+      // e.g. "fix-abc123_2026-08-17T00-00-00-000Z.bak" → "fix-abc123"
+      const match = entry.match(/^(fix-[a-z0-9]+)_/)
+      const id = match?.[1]
+      if (id && !activeIds.has(id)) {
+        staleBackups.push(entry)
+      }
     }
   }
 
@@ -252,6 +287,7 @@ export function inspectPrune(
     emptyRounds,
     totalLogEntries: entries.length,
     registryRounds: registry.rounds.length,
+    registryError,
     totalExperiences: bank.entries.length,
     experienceOversize: sweptBank.removed,
     totalDefenseEvents: defenseStream.events.length,
@@ -268,28 +304,60 @@ export function inspectPrune(
  *
  * The read-before-rewrite is a TOCTOU hot spot: a concurrent worker can append
  * a fresh audit line between our read and our atomic rewrite, and an atomic
- * rename would silently discard it. So instead of a single read+write we use a
- * bounded compare-and-append loop — after each rewrite we re-read the log and
+ * rename would silently discard it. So instead of a single read+write we take
+ * the cross-process log mutex for the whole loop AND keep a bounded
+ * compare-and-append loop behind it — after each rewrite we re-read the log and
  * retry whenever the file grew (a concurrent append slipped in). The loop
  * terminates when the file is stable or after `MAX_LOG_REWRITE_RETRIES`, and a
  * failure here is surfaced as a structured error instead of truncating the log.
  *
- * @returns the number of entries removed (best-effort) or 0 on error.
+ * Lock required: when the mutex cannot be taken (another process is appending
+ * and does not release within the wait budget) the rewrite is REFUSED with a
+ * structured error rather than proceeding unlocked — an unlocked rename can
+ * drop a concurrent appender's audit line (its fd points at the pre-rename
+ * inode) with no way to detect the loss afterwards.
+ *
+ * `deleted` is the TOTAL across every attempt: attempt 1 may already have
+ * removed entries before a retry is needed, and reporting only the final
+ * attempt's slice would under-count the audit entry (the pre-fix code returned
+ * `deleted: 0` on the exhaustion path even after real deletions).
+ *
+ * @param options.afterRewrite test hook run after each successful rewrite —
+ * simulates a concurrent appender landing lines mid-loop (production passes
+ * no hook).
+ * @param options.lock lock wait/stale budgets (tests pass short waits so the
+ * lock-unavailable refusal is exercised in milliseconds, not 5s).
+ * @returns the number of entries removed across all attempts, or 0 with an
+ *  `error` when nothing needed removing or the rewrite was refused/failed.
  */
-function rewriteDecisionLogKeepingRecent(projectRoot: string, cutoff: string): { deleted: number; error?: string } {
+export function rewriteDecisionLogKeepingRecent(
+  projectRoot: string,
+  cutoff: string,
+  options: { afterRewrite?: () => void; lock?: { waitMs?: number; staleMs?: number } } = {},
+): { deleted: number; error?: string } {
   const logPath = join(iterateDir(projectRoot), 'decision-log.jsonl')
   // Take the cross-process log lock for the ENTIRE loop: with the mutex held,
   // no concurrent appender can slip a fresh line into the read-before-rewrite
   // window, so the first attempt is nearly always the only one. (The retry
-  // loop stays as defense-in-depth for the lock-unavailable path.)
-  const release = acquireLogLock(projectRoot)
+  // loop stays as defense-in-depth for a line landing via the afterRewrite
+  // hook or an already-running appender's buffered write.)
+  const { acquired, release } = acquireLogLockChecked(projectRoot, options.lock)
+  if (!acquired) {
+    return {
+      deleted: 0,
+      error:
+        'failed to acquire the decision-log lock — refusing to rewrite the log unlocked ' +
+        '(a concurrent appender could lose an audit line). Retry after the other operation finishes.',
+    }
+  }
   try {
+    let deletedTotal = 0
     for (let attempt = 0; attempt < MAX_LOG_REWRITE_RETRIES; attempt++) {
       try {
         const entries = readDecisionEntries(projectRoot)
         const kept = entries.filter((e) => e.timestamp >= cutoff)
         const deleted = entries.length - kept.length
-        if (deleted === 0) return { deleted: 0 }
+        if (deleted === 0) return { deleted: deletedTotal }
         writeTextAtomic(logPath, kept.map((e) => JSON.stringify(e)).join('\n') + '\n')
         // The append-side entry-count cache is keyed by path and assumes "same
         // byte size ⇒ same count"; the rename above replaced the file with a
@@ -297,16 +365,21 @@ function rewriteDecisionLogKeepingRecent(projectRoot: string, cutoff: string): {
         // append can report a wrong entryCount when the sizes coincidentally
         // match.
         invalidateLogCountCache(logPath)
+        // Accumulate THIS attempt's deletions before the re-read: whatever the
+        // later attempts (or the exhaustion path) report, these entries are
+        // already gone from disk and must count toward the audit total.
+        deletedTotal += deleted
+        options.afterRewrite?.()
         // A concurrent appender (cross-process, lock-unavailable path) may have
         // landed new lines after our read. If the log grew during the write
         // window, re-read and prune again instead of accepting a lost audit trail.
         const after = readDecisionEntries(projectRoot)
-        if (after.length <= kept.length) return { deleted }
+        if (after.length <= kept.length) return { deleted: deletedTotal }
       } catch (err) {
-        return { deleted: 0, error: `failed to rewrite decision log: ${String(err)}` }
+        return { deleted: deletedTotal, error: `failed to rewrite decision log: ${String(err)}` }
       }
     }
-    return { deleted: 0, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` }
+    return { deleted: deletedTotal, error: `failed to rewrite decision log after ${MAX_LOG_REWRITE_RETRIES} attempts` }
   } finally {
     release()
   }
@@ -344,9 +417,10 @@ export function executePrune(
   }
 
   // 1. Rewrite the decision log, keeping only recent entries. Atomic
-  // (temp + rename) so a crash mid-write can never truncate the log; the
-  // bounded compare-and-append loop guards against a concurrent appender
-  // slipping a fresh audit line into the read-before-rewrite window.
+  // (temp + rename) under the cross-process log mutex — REFUSED with a
+  // structured error when the lock cannot be taken (an unlocked rename could
+  // drop a concurrent appender's audit line); the bounded compare-and-append
+  // loop behind it guards the remaining read-before-rewrite window.
   {
     const { deleted, error } = rewriteDecisionLogKeepingRecent(projectRoot, cutoff)
     result.deletedLogEntries = deleted
@@ -365,30 +439,41 @@ export function executePrune(
     }
   }
 
-  // 3. Delete stale backups.
-  for (const bak of report.staleBackups) {
-    try {
-      unlinkSync(join(fixesDir(projectRoot), bak))
-      result.deletedBackups.push(bak)
-    } catch (err) {
-      result.errors.push(`failed to delete backup ${bak}: ${String(err)}`)
+  // 3. Delete stale backups — REFUSED outright when the registry is present
+  // but unreadable: without a readable active-id set every backup would have
+  // classified stale, and one dryRun:false prune would wipe the whole rollback
+  // safety net. Surface the refusal as a structured error instead.
+  if (report.registryError) {
+    result.errors.push(report.registryError)
+  } else {
+    for (const bak of report.staleBackups) {
+      try {
+        unlinkSync(join(fixesDir(projectRoot), bak))
+        result.deletedBackups.push(bak)
+      } catch (err) {
+        result.errors.push(`failed to delete backup ${bak}: ${String(err)}`)
+      }
     }
   }
 
-  // 4. Trim empty rounds from the registry.
+  // 4. Trim empty rounds from the registry (locked read-modify-write: the
+  // registry read and rewrite must not interleave with another process's
+  // fix/rollback or the update is lost — see src/file-lock.ts).
   if (report.emptyRounds.length > 0) {
     try {
-      let registry = readRegistry(projectRoot)
-      const emptyRoundNos = new Set(report.emptyRounds)
-      // Drop whole empty rounds (records.length === 0) instead of only
-      // removing their records — an empty round has no records to remove, so
-      // the old loop was a no-op that still reported trimmedEmptyRounds.
-      registry = {
-        ...registry,
-        rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
-      }
-      registry = recomputeRoundCounts(registry)
-      writeJsonAtomic(fixRegistryPath(projectRoot), registry)
+      withProjectLock(projectRoot, 'fix-registry', () => {
+        let registry = readRegistry(projectRoot)
+        const emptyRoundNos = new Set(report.emptyRounds)
+        // Drop whole empty rounds (records.length === 0) instead of only
+        // removing their records — an empty round has no records to remove, so
+        // the old loop was a no-op that still reported trimmedEmptyRounds.
+        registry = {
+          ...registry,
+          rounds: registry.rounds.filter((r) => !emptyRoundNos.has(r.round) || (r.records?.length ?? 0) > 0),
+        }
+        registry = recomputeRoundCounts(registry)
+        writeJsonAtomic(fixRegistryPath(projectRoot), registry)
+      })
       result.trimmedEmptyRounds = report.emptyRounds.length
     } catch (err) {
       result.errors.push(`failed to trim empty rounds: ${String(err)}`)
@@ -445,13 +530,28 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
   ctx.tools.register(
     defineTool({
       name: 'iterate_prune',
+      // Pending-call card (#12): say up front whether this sweep is the default
+      // report-only preview or a REAL deletion — that distinction is prune's
+      // entire safety model, so it must be visible before the call runs. Pure:
+      // derived from args only.
+      presentCall: (args) => {
+        const a = args as { dryRun?: unknown }
+        const deleting = a.dryRun === false
+        return {
+          card: 'generic',
+          title: deleting
+            ? 'Prune stale .iterate/ artifacts (delete)'
+            : 'Prune preview (dry run — nothing deleted)',
+          kind: deleting ? 'delete' : 'read',
+        }
+      },
       description:
         'Inspect or clean up old iterate runtime artifacts (.iterate/). ' +
         'Defaults to dry-run (report-only, no deletion). Pass `dryRun: false` to actually prune. ' +
         'Manages: old decision-log entries, stale checkpoints, orphaned fix backups, empty fix rounds, ' +
         'stray temp files left by crashed atomic writes, experience-bank entries beyond the entry cap, ' +
         'and stale defense events. ' +
-        'Each deletion is logged to the decision log.',
+        'A non-dry-run appends ONE aggregate summary entry (counts per artifact class) to the decision log.',
       parameters: {
         dryRun: {
           type: 'boolean',
@@ -485,11 +585,14 @@ export function registerPruneTool(ctx: { tools: { register: (def: ReturnType<typ
           const report = value.report as Record<string, unknown> | undefined
           const result = value.result as Record<string, unknown> | undefined
           if (value.dryRun) {
+            const registryError = report?.registryError as string | null | undefined
             const lines = [
               `[dry-run] prune report (retainDays=${value.retainDays}):`,
               `  Decision-log entries to remove: ${report?.oldLogEntries ?? '?'} (of ${report?.totalLogEntries ?? '?'})`,
               `  Checkpoint to delete: ${report?.checkpointStale ? 'yes (stale)' : report?.hasCheckpoint ? 'no (fresh — resume point, kept)' : 'none'}`,
-              `  Stale backups to delete: ${(report?.staleBackups as string[] | undefined)?.length ?? 0}`,
+              registryError
+                ? `  Stale backups to delete: none — ${registryError}`
+                : `  Stale backups to delete: ${(report?.staleBackups as string[] | undefined)?.length ?? 0}`,
               `  Stray temp files to delete: ${(report?.staleTemps as string[] | undefined)?.length ?? 0}`,
               `  Empty rounds to trim: ${(report?.emptyRounds as number[] | undefined)?.length ?? 0}`,
               `  Experience entries to drop (over ${report?.totalExperiences ?? '?'} cap): ${report?.experienceOversize ?? 0} of ${report?.totalExperiences ?? '?'}`,

package/src/tools/quality-gate.ts

@@ -11,6 +11,7 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import { resolveProjectRootForExec } from '../config-loader.ts'
 import { readQualityGate, writeQualityGate, computeQualityGate, clearQualityGate } from './quality-store.ts'
+import { resultHeadline } from './present.ts'
 import type { QualityGateSnapshot } from '../types.ts'
 
 /** Valid severity values (kept in sync with QualityGateSnapshot counting). */
@@ -68,6 +69,14 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
   ctx.tools.register(
     defineTool({
       name: 'iterate_quality_gate',
+      // Result card (#12): the certificate render already opens with its
+      // headline ("✓ Quality Gate: PASS (score: 92)") — surface that as the
+      // card title so a completed gate query isn't a bare blob. Pure: reads
+      // only the rendered result (replay-safe); failures decline the card.
+      presentResult: (_args, result) => {
+        const title = resultHeadline(result)
+        return title ? { card: 'generic', title } : undefined
+      },
       // `read` never writes; `compute` persists the snapshot → only read
       // joins a parallel dispatch group.
       isConcurrencySafe: (args) => (args as { operation?: unknown }).operation === 'read',
@@ -88,12 +97,14 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
         dimensions: {
           type: 'array',
           items: { type: 'string' },
-          description: 'Dimensions to gate (required for compute).',
+          description: 'Dimensions to gate (required and must be non-empty for compute).',
         },
         findings: {
           type: 'json',
           description:
-            'Findings array (required for compute). Each item: { dimension, severity (critical|high|medium|low), file, line? }.',
+            'Findings array for compute (optional — defaults to []). Each item: ' +
+            '{ dimension, severity (critical|high|medium|low), file, line? }. Findings whose dimension ' +
+            'is not listed in `dimensions` are excluded from scoring and reported as warnings.',
         },
         validationResults: {
           type: 'json',
@@ -124,6 +135,11 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
             kind: { type: 'string' },
             operation: { type: 'string' },
             snapshot: { type: 'json' },
+            warnings: {
+              type: 'array',
+              items: { type: 'string' },
+              description: 'compute only: findings excluded from scoring because their dimension is not gated.',
+            },
             error: { type: 'string' },
           },
         },
@@ -148,6 +164,9 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
           if (snapshot.failReason) {
             lines.push('', `Fail Reason: ${snapshot.failReason}`)
           }
+          if (Array.isArray(value.warnings) && value.warnings.length > 0) {
+            lines.push('', 'Warnings:', ...value.warnings.map((w) => `  ! ${String(w)}`))
+          }
           if (operation === 'compute') {
             lines.push('', 'Quality gate snapshot computed and persisted.')
           }
@@ -182,6 +201,21 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
           const dimensions = Array.isArray(args.dimensions)
             ? args.dimensions.filter((d): d is string => typeof d === 'string' && d.length > 0)
             : []
+          // A compute without any gateable dimension would score an empty
+          // dimension list at overallScore 0 and PERSIST a fabricated FAIL
+          // certificate for a review that was simply never scoped. Refuse
+          // instead: no snapshot is written, and the caller gets a structured
+          // error naming the missing argument.
+          if (dimensions.length === 0) {
+            return {
+              ok: false,
+              kind: 'quality_gate',
+              operation: 'compute',
+              error:
+                'dimensions is required (and must be a non-empty array of dimension names) for operation "compute" — ' +
+                'without dimensions there is nothing to gate and no certificate can be computed.',
+            }
+          }
           const findings = Array.isArray(args.findings) ? args.findings.filter(isValidFinding) : []
           const validationResults = Array.isArray(args.validationResults)
             ? args.validationResults.filter(isValidValidationResult)
@@ -189,6 +223,24 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
           const findingsByRound = sanitizeRoundSeries(args.findingsByRound)
           const fixedByDimension = sanitizeNumberMap(args.fixedByDimension)
 
+          // Findings in dimensions outside the gated list are silently skipped
+          // by computeQualityGate (they never touch any dimension score) — a
+          // critical one still fails the gate globally, everything else just
+          // vanishes from the numbers. Surface those dimensions as warnings so
+          // the caller knows the score does NOT cover them; scoring is
+          // deliberately left unchanged.
+          const gated = new Set(dimensions)
+          const ungatedCounts = new Map<string, number>()
+          for (const finding of findings) {
+            if (!gated.has(finding.dimension)) {
+              ungatedCounts.set(finding.dimension, (ungatedCounts.get(finding.dimension) ?? 0) + 1)
+            }
+          }
+          const warnings = [...ungatedCounts].map(
+            ([dimension, count]) =>
+              `finding dimension "${dimension}" is not in the gated dimensions and was excluded from scoring (${count} finding${count === 1 ? '' : 's'})`,
+          )
+
           const snapshot = computeQualityGate({
             dimensions,
             findings,
@@ -205,6 +257,9 @@ export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnTy
             kind: 'quality_gate',
             operation: 'compute',
             snapshot: snapshot as unknown as JsonValue,
+            // Typed by the output schema as string[] — do not widen this to
+            // JsonValue or the execute return type stops matching the schema.
+            warnings,
           }
         }
 

package/src/tools/quality-store.ts

@@ -67,6 +67,11 @@ export function readQualityGate(projectRoot: string): QualityGateSnapshot {
             })
         : []
       return {
+        // Snapshot-level fallback timestamp: display-only metadata — the gate
+        // is a SINGLE snapshot file (overwritten wholesale), and nothing sorts
+        // or evicts by `timestamp`, so a missing/corrupt value degrading to
+        // "now" cannot affect retention or ordering. (Reaffirmed from the
+        // earlier review: comment only, behavior unchanged.)
         timestamp: typeof parsed.timestamp === 'string' ? parsed.timestamp : emptySnapshot().timestamp,
         overallStatus: status,
         overallScore: num(parsed.overallScore),
@@ -191,6 +196,12 @@ export function computeQualityGate(opts: {
   }
 
   for (const finding of findings) {
+    // Findings in dimensions outside the gated list land here with no matching
+    // `dimensionStats` entry and are skipped — they never touch any dimension
+    // score (only a global critical still fails the gate). Scoring stays
+    // unchanged by contract; the tool layer surfaces the excluded dimensions
+    // as `warnings` so the numbers are never silently incomplete
+    // (see src/tools/quality-gate.ts).
     const stats = dimensionStats[finding.dimension]
     if (stats) {
       stats.count++
@@ -207,7 +218,13 @@ export function computeQualityGate(opts: {
     // Score: 100 - (critical*30 + high*15 + medium*5 + low*1), capped at 0
     const penalty = stats.critical * 30 + stats.high * 15 + stats.medium * 5 + stats.low * 1
     const score = Math.max(0, 100 - penalty)
-    const status: 'pass' | 'warn' | 'fail' = score >= 80 ? 'pass' : score >= 50 ? 'warn' : 'fail'
+    // Arithmetic alone would grade a single critical as 100-30=70 → 'warn',
+    // while the snapshot's overall status is 'fail' (hasCritical below) — a
+    // certificate that contradicts itself ("WARN" on the dimension that made
+    // the gate fail). Any critical finding is a hard FAIL for that dimension,
+    // regardless of its score; non-critical dimensions keep the score bands.
+    const status: 'pass' | 'warn' | 'fail' =
+      stats.critical > 0 ? 'fail' : score >= 80 ? 'pass' : score >= 50 ? 'warn' : 'fail'
     const series = findingsByRound?.[dim]
     const convergenceRate = convergenceRateFor(Array.isArray(series) ? series : undefined, stats.count)