iterate-plugin 2.12.3 → 3.3.0

package/src/tools/quality-gate.ts

@@ -0,0 +1,196 @@
+/**
+ * src/tools/quality-gate.ts — quality gate query & write tool.
+ *
+ *   iterate_quality_gate — query the persisted quality certificate, or compute
+ *                          and persist a new one from review/validation data.
+ *
+ * Provides a machine-readable quality certificate for the current iteration.
+ */
+
+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 } from './quality-store.ts'
+import type { QualityGateSnapshot } from '../types.ts'
+
+/** Validate a single finding object; returns true when well-formed. */
+function isValidFinding(raw: unknown): raw is { dimension: string; severity: string; file: string; line?: number } {
+  if (!raw || typeof raw !== 'object') return false
+  const f = raw as Record<string, unknown>
+  return (
+    typeof f.dimension === 'string' &&
+    typeof f.severity === 'string' &&
+    typeof f.file === 'string' &&
+    (f.line === undefined || typeof f.line === 'number')
+  )
+}
+
+/** Validate a single validation result; returns true when well-formed. */
+function isValidValidationResult(raw: unknown): raw is { command: string; exitCode: number } {
+  if (!raw || typeof raw !== 'object') return false
+  const r = raw as Record<string, unknown>
+  return typeof r.command === 'string' && typeof r.exitCode === 'number' && Number.isFinite(r.exitCode)
+}
+
+/** Sanitize a caller-supplied per-dimension number map. */
+function sanitizeNumberMap(raw: unknown): Record<string, number> | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  const out: Record<string, number> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0) out[key] = value
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/** Sanitize a caller-supplied per-dimension round series map. */
+function sanitizeRoundSeries(raw: unknown): Record<string, number[]> | undefined {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
+  const out: Record<string, number[]> = {}
+  for (const [key, value] of Object.entries(raw)) {
+    if (Array.isArray(value)) {
+      const series = value
+        .filter((n): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0)
+      if (series.length > 0) out[key] = series
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined
+}
+
+/**
+ * Register the `iterate_quality_gate` tool.
+ * Reads the persisted quality certificate, or computes + persists a new one.
+ */
+export function registerQualityGateTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_quality_gate',
+      description:
+        'Query or write the quality gate status: dimension convergence rates, verification pass rates, ' +
+        'and overall PASS/FAIL status. ' +
+        'Operation "read" (default) returns the persisted machine-readable quality certificate. ' +
+        'Operation "compute" computes a fresh snapshot from this round\'s findings/validation results, ' +
+        'persists it to .iterate/quality-gate.json, and returns it.',
+      parameters: {
+        operation: {
+          type: 'string',
+          description: 'Operation: read (load persisted certificate) or compute (recompute + persist). Default: read.',
+          enum: ['read', 'compute'],
+        },
+        dimensions: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Dimensions to gate (required for compute).',
+        },
+        findings: {
+          type: 'json',
+          description:
+            'Findings array (required for compute). Each item: { dimension, severity (critical|high|medium|low), file, line? }.',
+        },
+        validationResults: {
+          type: 'json',
+          description: 'Validation results array (optional for compute). Each item: { command, exitCode }.',
+        },
+        findingsByRound: {
+          type: 'json',
+          description:
+            'Optional per-dimension NEW-finding counts across rounds (latest last) — used to compute real convergence rates. ' +
+            'Example: { "correctness": [5, 2, 0] }.',
+        },
+        fixedByDimension: {
+          type: 'json',
+          description: 'Optional per-dimension count of fixed findings, e.g. { "correctness": 3 }.',
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean', required: true },
+            kind: { type: 'string' },
+            operation: { type: 'string' },
+            snapshot: { type: 'json' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => {
+          if (!value.ok) return [{ type: 'text', text: `quality gate query failed: ${value.error}` }]
+          const operation = typeof value.operation === 'string' ? value.operation : 'read'
+          const snapshot = value.snapshot as unknown as QualityGateSnapshot
+          if (!snapshot) return [{ type: 'text', text: 'No quality gate data available.' }]
+
+          const statusEmoji = snapshot.overallStatus === 'pass' ? '✓' : snapshot.overallStatus === 'fail' ? '✗' : '○'
+          const lines = [
+            `${statusEmoji} Quality Gate: ${snapshot.overallStatus.toUpperCase()} (score: ${snapshot.overallScore})`,
+            `Verification: ${snapshot.passedChecks}/${snapshot.totalChecks} passed (${snapshot.verificationPassRate}%)`,
+            `Findings: ${snapshot.totalFindings} total (${snapshot.criticalCount} critical, ${snapshot.highCount} high, ${snapshot.mediumCount} medium, ${snapshot.lowCount} low)`,
+            '',
+            'Dimension Breakdown:',
+            ...snapshot.dimensions.map((d) => {
+              const dimStatus = d.status === 'pass' ? '✓' : d.status === 'warn' ? '!' : '✗'
+              return `  ${dimStatus} ${d.dimension}: score=${d.score}, convergence=${d.convergenceRate}%, findings=${d.findingsCount}, fixed=${d.fixedCount}`
+            }),
+          ]
+          if (snapshot.failReason) {
+            lines.push('', `Fail Reason: ${snapshot.failReason}`)
+          }
+          if (operation === 'compute') {
+            lines.push('', 'Quality gate snapshot computed and persisted.')
+          }
+          return [{ type: 'text', text: lines.join('\n') }]
+        },
+      },
+
+      async execute(args, exec) {
+        const resolved = resolveProjectRootForExec(exec, args.path)
+        if (!resolved.ok) return { ok: false, kind: 'quality_gate', error: resolved.reason }
+        const projectRoot = resolved.root
+
+        const operation = typeof args.operation === 'string' ? args.operation : 'read'
+
+        if (operation === 'compute') {
+          const dimensions = Array.isArray(args.dimensions)
+            ? args.dimensions.filter((d): d is string => typeof d === 'string' && d.length > 0)
+            : []
+          const findings = Array.isArray(args.findings) ? args.findings.filter(isValidFinding) : []
+          const validationResults = Array.isArray(args.validationResults)
+            ? args.validationResults.filter(isValidValidationResult)
+            : undefined
+          const findingsByRound = sanitizeRoundSeries(args.findingsByRound)
+          const fixedByDimension = sanitizeNumberMap(args.fixedByDimension)
+
+          const snapshot = computeQualityGate({
+            dimensions,
+            findings,
+            validationResults,
+            findingsByRound,
+            fixedByDimension,
+          })
+          const write = writeQualityGate(projectRoot, snapshot)
+          if (!write.ok) {
+            return { ok: false, kind: 'quality_gate', operation: 'compute', error: write.error }
+          }
+          return {
+            ok: true,
+            kind: 'quality_gate',
+            operation: 'compute',
+            snapshot: snapshot as unknown as JsonValue,
+          }
+        }
+
+        const snapshot = readQualityGate(projectRoot)
+        return {
+          ok: true,
+          kind: 'quality_gate',
+          operation: 'read',
+          snapshot: snapshot as unknown as JsonValue,
+        }
+      },
+    }),
+  )
+}

package/src/tools/quality-store.ts

@@ -0,0 +1,208 @@
+/**
+ * src/tools/quality-store.ts — quality gate storage layer.
+ *
+ * Provides read/write access to quality gate data stored in
+ * .iterate/quality-gate.json. Quality gate snapshots are generated
+ * from review results and validation outcomes.
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { QualityGateSnapshot, QualityGateDimension } from '../types.ts'
+
+const QUALITY_GATE_FILE = 'quality-gate.json'
+
+/** Default empty quality gate snapshot. */
+function emptySnapshot(): QualityGateSnapshot {
+  return {
+    timestamp: new Date().toISOString(),
+    overallStatus: 'pending',
+    overallScore: 0,
+    dimensions: [],
+    verificationPassRate: 0,
+    totalChecks: 0,
+    passedChecks: 0,
+    failedChecks: 0,
+    totalFindings: 0,
+    criticalCount: 0,
+    highCount: 0,
+    mediumCount: 0,
+    lowCount: 0,
+  }
+}
+
+/** Read the quality gate snapshot from disk. */
+export function readQualityGate(projectRoot: string): QualityGateSnapshot {
+  const filePath = path.join(projectRoot, '.iterate', QUALITY_GATE_FILE)
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const parsed = JSON.parse(content) as QualityGateSnapshot
+    if (parsed && typeof parsed === 'object') {
+      return parsed
+    }
+  } catch {
+    // File not found or invalid JSON
+  }
+  return emptySnapshot()
+}
+
+/**
+ * Write the quality gate snapshot to disk.
+ * Returns `{ ok: true }` on success or `{ ok: false, error }` when the write
+ * fails — a caller must surface the failure instead of reporting success for
+ * a snapshot that was never persisted.
+ */
+export function writeQualityGate(
+  projectRoot: string,
+  snapshot: QualityGateSnapshot,
+): { ok: true } | { ok: false; error: string } {
+  const dirPath = path.join(projectRoot, '.iterate')
+  const filePath = path.join(dirPath, QUALITY_GATE_FILE)
+
+  try {
+    if (!fs.existsSync(dirPath)) {
+      fs.mkdirSync(dirPath, { recursive: true })
+    }
+    fs.writeFileSync(filePath, JSON.stringify(snapshot, null, 2), 'utf-8')
+  } catch (err) {
+    return { ok: false, error: `unable to write ${filePath}: ${String(err)}` }
+  }
+  return { ok: true }
+}
+
+/**
+ * Compute the convergence rate for a dimension.
+ *
+ * Convergence measures how much NEW-finding volume shrank across rounds:
+ * `(first - last) / first` from the dimension's per-round findings series,
+ * expressed as a 0-100 percentage, clamped. A series with no fresh findings
+ * (or a dimension never reporting a first-round reading) counts as fully
+ * converged (100). Returns 0 — no measurable improvement — when a reading
+ * exists but the series is empty or malformed.
+ */
+export function convergenceRateFor(series: number[] | undefined, currentCount: number): number {
+  if (Array.isArray(series) && series.length > 0) {
+    const first = series.find((n) => typeof n === 'number' && Number.isFinite(n))
+    const last = [...series].reverse().find((n) => typeof n === 'number' && Number.isFinite(n))
+    if (first === undefined || last === undefined) return currentCount === 0 ? 100 : 0
+    if (first <= 0) return currentCount === 0 ? 100 : 0
+    const raw = ((first - Math.max(0, last)) / first) * 100
+    return Math.max(0, Math.min(100, Math.round(raw)))
+  }
+  return currentCount === 0 ? 100 : 0
+}
+
+/** Compute a quality gate snapshot from review data. */
+export function computeQualityGate(opts: {
+  dimensions: string[]
+  findings: Array<{
+    dimension: string
+    severity: string
+    file: string
+    line?: number
+  }>
+  validationResults?: Array<{
+    command: string
+    exitCode: number
+  }>
+  /** Per-dimension sequence of NEW-finding counts across rounds, newest last. */
+  findingsByRound?: Record<string, number[]>
+  /** Per-dimension count of findings already fixed this iteration. */
+  fixedByDimension?: Record<string, number>
+}): QualityGateSnapshot {
+  const { dimensions, findings, validationResults, findingsByRound, fixedByDimension } = opts
+
+  // Count findings by severity
+  const criticalCount = findings.filter((f) => f.severity === 'critical').length
+  const highCount = findings.filter((f) => f.severity === 'high').length
+  const mediumCount = findings.filter((f) => f.severity === 'medium').length
+  const lowCount = findings.filter((f) => f.severity === 'low').length
+  const totalFindings = findings.length
+
+  // Compute dimension scores
+  const dimensionStats: Record<string, { count: number; critical: number; high: number; medium: number; low: number }> = {}
+  for (const dim of dimensions) {
+    dimensionStats[dim] = { count: 0, critical: 0, high: 0, medium: 0, low: 0 }
+  }
+
+  for (const finding of findings) {
+    const stats = dimensionStats[finding.dimension]
+    if (stats) {
+      stats.count++
+      if (finding.severity === 'critical') stats.critical++
+      else if (finding.severity === 'high') stats.high++
+      else if (finding.severity === 'medium') stats.medium++
+      else stats.low++
+    }
+  }
+
+  // Compute dimension-level quality gates
+  const dimensionGates: QualityGateDimension[] = dimensions.map((dim) => {
+    const stats = dimensionStats[dim] || { count: 0, critical: 0, high: 0, medium: 0, low: 0 }
+    // 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'
+    const series = findingsByRound?.[dim]
+    const convergenceRate = convergenceRateFor(Array.isArray(series) ? series : undefined, stats.count)
+
+    return {
+      dimension: dim,
+      convergenceRate,
+      findingsCount: stats.count,
+      fixedCount: fixedByDimension?.[dim] ?? 0,
+      score,
+      status,
+    }
+  })
+
+  // Compute verification pass rate
+  const totalChecks = validationResults?.length ?? 0
+  const passedChecks = validationResults?.filter((r) => r.exitCode === 0).length ?? 0
+  const failedChecks = totalChecks - passedChecks
+  const verificationPassRate = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 0
+
+  // Compute overall score (weighted average of dimension scores)
+  const overallScore = dimensionGates.length > 0
+    ? Math.round(dimensionGates.reduce((sum, d) => sum + d.score, 0) / dimensionGates.length)
+    : 0
+
+  // Determine overall status
+  const hasCritical = criticalCount > 0
+  const hasHighFail = dimensionGates.some((d) => d.status === 'fail')
+  const verificationFails = totalChecks > 0 && failedChecks > 0
+
+  let overallStatus: 'pass' | 'fail' | 'pending' = 'pass'
+  let failReason: string | undefined
+
+  if (hasCritical) {
+    overallStatus = 'fail'
+    failReason = `${criticalCount} critical findings present`
+  } else if (hasHighFail) {
+    overallStatus = 'fail'
+    failReason = 'One or more dimensions failed quality gate'
+  } else if (verificationFails) {
+    overallStatus = 'fail'
+    failReason = `${failedChecks} validation checks failed`
+  } else if (overallScore < 70) {
+    overallStatus = 'fail'
+    failReason = `Overall score ${overallScore} below threshold (70)`
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    overallStatus,
+    overallScore,
+    dimensions: dimensionGates,
+    verificationPassRate,
+    totalChecks,
+    passedChecks,
+    failedChecks,
+    failReason,
+    totalFindings,
+    criticalCount,
+    highCount,
+    mediumCount,
+    lowCount,
+  }
+}

package/src/tools/transcript.ts

@@ -136,6 +136,11 @@ export function registerTranscriptTool(ctx: {
           description: 'For `capture`: run mode ("dry-run" | "normal"). Default dry-run.',
           enum: ['dry-run', 'normal'],
         },
+        taskMode: {
+          type: 'string',
+          description: 'For `capture`: harness execution mode ("code" | "iterate"). Default derives from the review loop (iterate).',
+          enum: ['code', 'iterate'],
+        },
         goal: { type: 'string', description: 'For `capture`: run goal.' },
         maxRounds: { type: 'integer', description: 'For `capture`: round cap.' },
         roundsExecuted: { type: 'integer', description: 'For `capture`: number of rounds actually executed.' },
@@ -229,10 +234,11 @@ export function registerTranscriptTool(ctx: {
 
         // capture
         const mode = args.mode === 'normal' ? 'normal' : 'dry-run'
+        const taskMode = args.taskMode === 'code' || args.taskMode === 'iterate' ? args.taskMode : undefined
         const goal = typeof args.goal === 'string' ? args.goal : ''
         const maxRounds =
           typeof args.maxRounds === 'number' ? Math.floor(args.maxRounds) : 0
-        const builder = new ReviewTranscriptBuilder({ project: projectRoot, mode, approval, goal, maxRounds })
+        const builder = new ReviewTranscriptBuilder({ project: projectRoot, mode, taskMode, approval, goal, maxRounds })
         const report = args.report as Record<string, unknown> | null | undefined
         const reportFindings: unknown =
           report && typeof report === 'object' && Array.isArray(report.findings)
@@ -300,6 +306,7 @@ function rehydrateBuilder(manifest: TranscriptManifest, approval: 'ask' | 'deny'
   const builder = new ReviewTranscriptBuilder({
     project: manifest.project,
     mode: manifest.mode ?? null,
+    taskMode: manifest.taskMode ?? null,
     approval,
     goal: manifest.goal,
     maxRounds: manifest.maxRounds,

package/src/transcript.ts

@@ -126,6 +126,7 @@ function mergeReportIntoThread(
 export class ReviewTranscriptBuilder {
   private readonly project: string
   private readonly mode: 'dry-run' | 'normal' | null
+  private readonly taskMode: 'code' | 'iterate' | null
   private readonly approval: 'ask' | 'deny' | 'allow'
   private goal = ''
   private readonly phases: string[] = []
@@ -144,6 +145,7 @@ export class ReviewTranscriptBuilder {
   constructor(input: {
     project: string
     mode?: 'dry-run' | 'normal' | null
+    taskMode?: 'code' | 'iterate' | null
     approval?: 'ask' | 'deny' | 'allow'
     goal?: string
     maxRounds?: number
@@ -152,6 +154,14 @@ export class ReviewTranscriptBuilder {
     this.project = input.project || ''
     this.mode =
       input.mode === 'dry-run' || input.mode === 'normal' ? input.mode : null
+    // v3.0: task_mode indicator. An explicit valid value wins; otherwise a
+    // run that exercises the review loop (any mode) defaults to "iterate".
+    this.taskMode =
+      input.taskMode === 'code' || input.taskMode === 'iterate'
+        ? input.taskMode
+        : input.mode !== null && input.mode !== undefined
+          ? 'iterate'
+          : null
     this.approval =
       input.approval === 'ask' || input.approval === 'deny' || input.approval === 'allow'
         ? input.approval
@@ -393,6 +403,7 @@ export class ReviewTranscriptBuilder {
       updatedAt: this.updatedAt,
       active: this.active,
       mode: this.mode,
+      taskMode: this.taskMode,
       goal: this.goal,
       phases: this.phases,
       round: this.round,

package/src/types.ts

@@ -230,6 +230,20 @@ export interface IterationStatus {
   resumeCount: number
   checkpoint: IterationCheckpoint | null
   lastUpdated: string | null
+  /** v3.0: Quality gate snapshot */
+  qualityGate?: QualityGateSnapshot
+  /** v3.0: Experience bank summary */
+  experienceBank?: {
+    totalEntries: number
+    totalHits: number
+  }
+  /** v3.0: Defense events summary */
+  defenseEvents?: {
+    totalEvents: number
+    counts: Record<DefenseEventType, number>
+  }
+  /** v3.0: task_mode from harness */
+  taskMode?: 'code' | 'iterate' | null
 }
 
 /** ─── Runtime observatory (transcript) ───────────────────────────────────── */
@@ -331,4 +345,108 @@ export interface TranscriptManifest {
     active: boolean
     policy: 'ask' | 'deny' | 'allow'
   }
+  /** v3.0: task_mode indicator from harness status */
+  taskMode?: 'code' | 'iterate' | null
+}
+
+// ─── v3.0: Quality Gate ──────────────────────────────────────────────────────
+
+/** A single dimension's quality gate status. */
+export interface QualityGateDimension {
+  dimension: string
+  convergenceRate: number
+  findingsCount: number
+  fixedCount: number
+  /** 0-100 score based on findings severity and count */
+  score: number
+  status: 'pass' | 'warn' | 'fail'
+}
+
+/** Quality gate snapshot for the current iteration. */
+export interface QualityGateSnapshot {
+  timestamp: string
+  overallStatus: 'pass' | 'fail' | 'pending'
+  overallScore: number
+  dimensions: QualityGateDimension[]
+  verificationPassRate: number
+  totalChecks: number
+  passedChecks: number
+  failedChecks: number
+  /** Reason for overall FAIL status, if applicable */
+  failReason?: string
+  /** Total findings across all dimensions */
+  totalFindings: number
+  /** Findings by severity */
+  criticalCount: number
+  highCount: number
+  mediumCount: number
+  lowCount: number
+}
+
+// ─── v3.0: Experience Bank ───────────────────────────────────────────────────
+
+/** A single experience entry in the experience bank. */
+export interface ExperienceEntry {
+  id: string
+  timestamp: string
+  dimension: string
+  pattern: string
+  description: string
+  /** The fix that was applied and verified */
+  verifiedFix: string
+  /** Files involved in this experience */
+  files: string[]
+  /** How many times this pattern has been encountered */
+  hitCount: number
+  /** Last time this experience was hit */
+  lastHitAt?: string
+  /** Tags for categorization */
+  tags: string[]
+  /** Related finding summary */
+  findingSummary: string
+  /** Severity of the original finding */
+  severity: 'critical' | 'high' | 'medium' | 'low'
+}
+
+/** Experience bank state for the project. */
+export interface ExperienceBank {
+  entries: ExperienceEntry[]
+  lastUpdated: string
+  totalHits: number
+}
+
+// ─── v3.0: Defense Events ────────────────────────────────────────────────────
+
+/** Defense event types */
+export type DefenseEventType =
+  | 'precondition_failed'
+  | 'rollback'
+  | 'invariant_violated'
+  | 'assumption_falsified'
+
+/** A single defense event recorded during iteration. */
+export interface DefenseEvent {
+  id: string
+  timestamp: string
+  round: number
+  type: DefenseEventType
+  /** What was being checked */
+  description: string
+  /** The defense that was triggered */
+  defense: string
+  /** Outcome: what was protected against */
+  outcome: string
+  /** Optional file/location context */
+  file?: string
+  line?: number
+  /** Severity of the event */
+  severity: 'critical' | 'high' | 'medium' | 'low'
+}
+
+/** Defense events stream for the current iteration. */
+export interface DefenseEventStream {
+  events: DefenseEvent[]
+  lastUpdated: string
+  /** Summary counts by type */
+  counts: Record<DefenseEventType, number>
 }