iterate-plugin 3.11.0 → 3.13.0

package/src/client/i18n.ts

@@ -446,11 +446,53 @@ export const EN: Record<string, string> = {
   '防线：{a0}': 'Defense: {a0}',
   没有匹配该类型的防御事件: 'No defense events of this type',
 
+  // ── F11 preflight ────────────────────────────────────────────────────────
+  开跑预检: 'Preflight',
+  待预检: 'Not run yet',
+  未就绪: 'Not ready',
+  '复制 iterate_preflight 预检指令（含 JSON 参数）':
+    'Copy the iterate_preflight readiness instruction (JSON arguments included)',
+  运行预检: 'Run preflight',
+  开跑预检清单: 'Preflight checklist',
+  预检结果: 'Preflight result',
+  '开跑前先预检：确认验证命令、Git、工作区、陈旧门禁与中断断点都已就绪，避免开跑后才发现环境问题。':
+    'Run preflight first: confirm validation commands, git, the working tree, a stale gate and an interrupted checkpoint are ready, so you do not discover an environment problem mid-run.',
+  复制预检指令: 'Copy preflight instruction',
+  验证命令: 'Validation commands',
+  '已配置 {a0} 条验证命令': '{a0} validation command(s) configured',
+  '未配置 validation.commands（阻断项）—— 检测到 {a0} 项目，建议：{a1}':
+    'validation.commands is not configured (blocking) — detected {a0} project; suggested: {a1}',
+  '未配置 validation.commands —— 本轮无法证明修复，属阻断项':
+    'validation.commands is not configured — the run cannot prove fixes (blocking)',
+  'Git 仓库': 'Git repository',
+  '已检测到 Git 仓库': 'Git repository detected',
+  '不是 Git 仓库 —— changed-only 范围与 iterate_diff 需要它':
+    'Not a git repository — changed-only scope and iterate_diff need one',
+  工作区: 'Working tree',
+  '未提交改动：未知': 'Uncommitted changes: unknown',
+  '{a0} 个未提交/未跟踪文件 —— 建议先 commit 或 stash':
+    '{a0} uncommitted/untracked file(s) — commit or stash first',
+  工作区干净: 'Working tree clean',
+  陈旧门禁: 'Stale gate',
+  '磁盘上残留 FAIL 质量门禁 —— 开新轮前先清除':
+    'A stale FAIL quality gate is persisted — clear it before a fresh run',
+  '质量门禁：{a0}': 'Quality gate: {a0}',
+  无持久化质量门禁: 'No persisted quality gate',
+  中断断点: 'Interrupted checkpoint',
+  '存在中断断点（已恢复 {a0} 次）—— 恢复或清除后再开跑':
+    'An interrupted checkpoint is waiting (resumed {a0}x) — resume or clear it first',
+  无中断断点: 'No interrupted checkpoint',
+  配置验证命令: 'Configure validation',
+  应用建议: 'Apply suggestion',
+  恢复断点: 'Resume checkpoint',
+  '阻断 {a0} · 警告 {a1}': 'Blocking {a0} · warnings {a1}',
+  '预检失败：{a0}': 'Preflight failed: {a0}',
+  '预检只读，不会修改配置或文件。': 'Preflight is read-only; it never modifies config or files.',
+
   // ── copy feedback ────────────────────────────────────────────────────────
   已复制: 'Copied',
   复制失败: 'Copy failed',
 }
-
 let current: Lang = 'zh'
 let storage: LangStorage | null = null
 const listeners = new Set<(lang: Lang) => void>()

package/src/client/index.ts

@@ -75,6 +75,9 @@ import {
   scanSessionForQualityGate,
   scanSessionForExperienceBank,
   scanSessionForDefenseEvents,
+  scanSessionForPreflight,
+  buildPreflightInstruction,
+  buildValidationApplyInstruction,
   filterLiveEntries,
   filterTimelineEntries,
   serializeObservatoryExport,
@@ -336,6 +339,24 @@ interface ObsQualityGate {
   dimensions?: ObsQualityGateDimension[]
 }
 
+/** One readiness check from `iterate_preflight` (F11). `detail` is structured
+ *  facts the panel localizes into a sentence. */
+interface ObsPreflightCheck {
+  id?: string
+  status?: string
+  detail?: Record<string, unknown>
+}
+
+/** Latest `iterate_preflight` report scanned out of the session stream. */
+interface ObsPreflight {
+  ok?: boolean
+  ready?: boolean
+  blocking?: number
+  warnings?: number
+  error?: string | null
+  checks?: ObsPreflightCheck[]
+}
+
 interface ObsExperienceEntry {
   id?: string
   timestamp?: string
@@ -583,6 +604,7 @@ const ITERATE_CSS = `
 .iterate-gate[data-status="pass"] { color: var(--dsw-alias-state-success-primary); background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); }
 .iterate-gate[data-status="fail"] { color: var(--dsw-alias-state-error-primary); background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 28%, transparent); }
 .iterate-gate[data-status="pending"] { color: var(--dsw-alias-label-secondary); background: color-mix(in srgb, var(--dsw-alias-label-secondary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-label-secondary) 28%, transparent); }
+.iterate-gate[data-status="warn"] { color: var(--dsw-alias-state-warn-primary); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-warn-primary) 28%, transparent); }
 
 /* v3.0: Experience bank hit highlight */
 .iterate-exp-hit { display: inline-flex; align-items: center; gap: 6px; padding: 2px 8px; border-radius: 6px; background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 12%, transparent); border: 1px solid color-mix(in srgb, var(--dsw-alias-state-success-primary) 28%, transparent); font-size: 11px; color: var(--dsw-alias-state-success-primary); }
@@ -2179,6 +2201,8 @@ const OBS_TABS = [
   { key: 'f8', label: { zh: '质量门禁', en: 'Quality gate' }, hotkey: '8' },
   { key: 'f9', label: { zh: '经验银行', en: 'Experience bank' }, hotkey: '9' },
   { key: 'f10', label: { zh: '防御事件', en: 'Defense events' }, hotkey: '0' },
+  // v3.12: pre-run readiness checklist (validation/git/dirty-tree/stale-gate/checkpoint)
+  { key: 'f11', label: { zh: '开跑预检', en: 'Preflight' }, hotkey: '' },
 ] as const
 
 /** Digit → tab id. `1-9` map to F1–F9, `0` to F10, `-` back to the live feed
@@ -2267,6 +2291,12 @@ function latestDefenseEvents(session: unknown): ObsDefenseResult | null {
   return scanSessionForDefenseEvents(session) as ObsDefenseResult | null
 }
 
+/** Find the latest preflight report inside a session snapshot. */
+function latestPreflight(session: unknown): ObsPreflight | null {
+  if (!session) return null
+  return scanSessionForPreflight(session) as ObsPreflight | null
+}
+
 /** Build a human-pasteable `iterate_fix` instruction for one finding.
  *  Gap #10: delegates to the shared builder so the payload always names the
  *  four required `iterate_fix` params (file / content / finding / round) and
@@ -2295,6 +2325,7 @@ function ObservatoryPanel(props: SlotProps) {
   const qualityGate = latestQualityGate(session)
   const experienceBank = latestExperienceBank(session)
   const defenseEvents = latestDefenseEvents(session)
+  const preflight = latestPreflight(session)
 
   const [open, setOpen] = React.useState(false)
   const [tab, setTab] = React.useState('live')
@@ -3356,6 +3387,195 @@ function ObservatoryPanel(props: SlotProps) {
     )
   }
 
+  // ── F11: Preflight readiness ──────────────────────────────────────────────
+  // v3.12: renders the latest iterate_preflight checklist scanned from the
+  // session stream. Each warn/fail row offers the exact fix instruction
+  // (configure validation, clear a stale gate, resume an interrupted
+  // checkpoint) so the environment is repaired BEFORE a round is spent on it.
+  const renderPreflight = () => {
+    const preflightInstruction = buildPreflightInstruction()
+    const report = preflight
+    const hasReport = report !== null && Array.isArray(report.checks)
+    const ready = report !== null && report.ready === true
+    const blocking = Number(report && report.blocking != null ? report.blocking : 0)
+    const warnings = Number(report && report.warnings != null ? report.warnings : 0)
+    const statusLabel = !hasReport ? t('待预检') : ready ? t('就绪') : t('未就绪')
+    const statusTone = !hasReport ? 'pending' : ready ? 'pass' : 'fail'
+    const headerBar = React.createElement('div', { className: 'iterate-obs-bar', style: { marginBottom: 8 } },
+      React.createElement('b', {}, t('开跑预检')),
+      React.createElement('span', { className: 'iterate-gate', 'data-status': statusTone }, statusLabel),
+      React.createElement('button', {
+        className: 'iterate-btn', 'data-primary': '', 'data-copied': copiedKey === 'preflight' ? '' : undefined,
+        onClick: () => copyInstruction('preflight', preflightInstruction),
+        title: t('复制 iterate_preflight 预检指令（含 JSON 参数）'),
+      }, copiedKey === 'preflight' ? t('已复制') : t('运行预检')),
+    )
+
+    if (!hasReport) {
+      return React.createElement('div', {},
+        headerBar,
+        React.createElement('div', { className: 'iterate-obs-block' },
+          React.createElement('div', { className: 'iterate-obs-block-head' },
+            React.createElement('span', {}, t('开跑预检清单')),
+            React.createElement('span', { className: 'iterate-obs-badge' }, 'v3.12'),
+          ),
+          React.createElement('div', { className: 'iterate-obs-block-body' },
+            React.createElement('div', { className: 'iterate-obs-msg' },
+              // Gap #4: separate "pulled and empty" from "never pulled".
+              diskEmptyStateText(toolCalledInSession(session, 'iterate_preflight'), t('预检结果'), getLang()),
+            ),
+            React.createElement('div', { className: 'iterate-obs-msg', style: { marginTop: 6 } },
+              t('开跑前先预检：确认验证命令、Git、工作区、陈旧门禁与中断断点都已就绪，避免开跑后才发现环境问题。'),
+            ),
+            React.createElement('div', { className: 'iterate-obs-bar', style: { marginTop: 8 } },
+              React.createElement('button', {
+                className: 'iterate-btn', 'data-copied': copiedKey === 'preflight-instr' ? '' : undefined,
+                onClick: () => copyInstruction('preflight-instr', preflightInstruction),
+                title: t('复制预检指令'),
+              }, copiedKey === 'preflight-instr' ? t('已复制') : t('复制预检指令')),
+            ),
+          ),
+        ),
+      )
+    }
+
+    // A tool-level failure (bad path, root refused) carries no usable checks —
+    // surface the error instead of a misleading "ready, 0 blocking" summary.
+    if (report && report.ok === false) {
+      return React.createElement('div', {},
+        headerBar,
+        React.createElement('div', { className: 'iterate-obs-block' },
+          React.createElement('div', { className: 'iterate-obs-block-head' },
+            React.createElement('span', {}, t('开跑预检清单')),
+            React.createElement('span', { className: 'iterate-obs-badge' }, 'v3.12'),
+          ),
+          React.createElement('div', { className: 'iterate-obs-block-body' },
+            React.createElement('div', { className: 'iterate-obs-msg' },
+              tf('预检失败：{a0}', { a0: String(report.error || '') }),
+            ),
+          ),
+        ),
+      )
+    }
+
+    // Localized label + detail per check id. Detail is structured facts from
+    // the tool, so the panel — not the tool — owns the wording/language.
+    const CHECK_META: Record<string, { label: string; detail: (d: Record<string, unknown>) => string }> = {
+      validation: {
+        label: t('验证命令'),
+        detail: (d) => {
+          const n = Number(d.commandCount ?? 0)
+          if (n > 0) return tf('已配置 {a0} 条验证命令', { a0: n })
+          const suggested = Array.isArray(d.suggestedCommands)
+            ? d.suggestedCommands.map((c) => String(c)).filter((c) => c.length > 0)
+            : []
+          if (suggested.length > 0) {
+            return tf('未配置 validation.commands（阻断项）—— 检测到 {a0} 项目，建议：{a1}', {
+              a0: String(d.ecosystem || ''),
+              a1: suggested.join(' · '),
+            })
+          }
+          return t('未配置 validation.commands —— 本轮无法证明修复，属阻断项')
+        },
+      },
+      git: {
+        label: t('Git 仓库'),
+        detail: (d) => (d.isRepo === true ? t('已检测到 Git 仓库') : t('不是 Git 仓库 —— changed-only 范围与 iterate_diff 需要它')),
+      },
+      'dirty-tree': {
+        label: t('工作区'),
+        detail: (d) => {
+          const n = d.changedFiles
+          if (n === null || n === undefined) return t('未提交改动：未知')
+          const num = Number(n)
+          return num > 0
+            ? tf('{a0} 个未提交/未跟踪文件 —— 建议先 commit 或 stash', { a0: num })
+            : t('工作区干净')
+        },
+      },
+      'stale-gate': {
+        label: t('陈旧门禁'),
+        detail: (d) => {
+          const s = d.overallStatus
+          if (s === 'fail') return t('磁盘上残留 FAIL 质量门禁 —— 开新轮前先清除')
+          return s ? tf('质量门禁：{a0}', { a0: String(s) }) : t('无持久化质量门禁')
+        },
+      },
+      'interrupted-checkpoint': {
+        label: t('中断断点'),
+        detail: (d) => {
+          if (d.interrupted === true) {
+            const rc = Number(d.resumeCount ?? 0)
+            return tf('存在中断断点（已恢复 {a0} 次）—— 恢复或清除后再开跑', { a0: rc })
+          }
+          return t('无中断断点')
+        },
+      },
+    }
+
+    // Repair action per check id; null = guidance only (no tool can fix it).
+    const fixFor = (id: string, detail: Record<string, unknown>): { key: string; label: string; instruction: string } | null => {
+      switch (id) {
+        case 'validation': {
+          const suggested = Array.isArray(detail.suggestedCommands)
+            ? detail.suggestedCommands.map((c) => String(c)).filter((c) => c.length > 0)
+            : []
+          if (suggested.length > 0) {
+            return {
+              key: 'preflight-fix-validation',
+              label: t('应用建议'),
+              instruction: buildValidationApplyInstruction(suggested),
+            }
+          }
+          return { key: 'preflight-fix-validation', label: t('配置验证命令'), instruction: buildConfigFieldInstruction('validation.commands') }
+        }
+        case 'stale-gate':
+          return { key: 'preflight-fix-gate', label: t('清除门禁'), instruction: buildQualityGateClearInstruction() }
+        case 'interrupted-checkpoint':
+          return { key: 'preflight-fix-checkpoint', label: t('恢复断点'), instruction: buildCheckpointResumeInstruction() }
+        default:
+          return null
+      }
+    }
+
+    const rows = (report.checks || []).map((c, i) => {
+      const id = String(c.id || '')
+      const status = String(c.status || 'warn')
+      const meta = CHECK_META[id]
+      const label = meta ? meta.label : id || '?'
+      const detailText = meta ? meta.detail(c.detail || {}) : ''
+      const fix = status !== 'pass' ? fixFor(id, c.detail || {}) : null
+      return React.createElement('div', { key: `pf-${i}`, className: 'iterate-obs-row' },
+        React.createElement('span', { className: 'iterate-gate', 'data-status': status }, status.toUpperCase()),
+        React.createElement('b', {}, label),
+        React.createElement('span', { className: 'iterate-obs-msg' }, detailText),
+        fix
+          ? React.createElement('button', {
+              className: 'iterate-btn', 'data-copied': copiedKey === fix.key ? '' : undefined,
+              onClick: () => copyInstruction(fix.key, fix.instruction),
+              title: fix.instruction,
+            }, copiedKey === fix.key ? t('已复制') : fix.label)
+          : null,
+      )
+    })
+
+    return React.createElement('div', {},
+      headerBar,
+      React.createElement('div', { className: 'iterate-obs-block' },
+        React.createElement('div', { className: 'iterate-obs-block-head' },
+          React.createElement('span', {}, t('开跑预检清单')),
+          React.createElement('span', { className: 'iterate-obs-head-meta' },
+            tf('阻断 {a0} · 警告 {a1}', { a0: blocking, a1: warnings }),
+          ),
+        ),
+        React.createElement('div', { className: 'iterate-obs-block-body' },
+          React.createElement('div', { className: 'iterate-obs-msg' }, t('预检只读，不会修改配置或文件。')),
+          ...rows,
+        ),
+      ),
+    )
+  }
+
   // ── Live: real-time secondary-subagent activity stream (newest first) ─────
   const renderLive = () => {
     const liveEntries = manifest.live || []
@@ -3440,6 +3660,7 @@ function ObservatoryPanel(props: SlotProps) {
       case 'f8': return renderQualityGate()
       case 'f9': return renderExperienceBank()
       case 'f10': return renderDefenseEvents()
+      case 'f11': return renderPreflight()
       default: return null
     }
   }

package/src/index.ts

@@ -46,6 +46,7 @@ import { registerExperienceBankTool } from './tools/experience-bank.ts'
 import { registerQualityGateTool } from './tools/quality-gate.ts'
 import { registerDefenseEventsTool } from './tools/defense-events.ts'
 import { registerReportTool } from './tools/report.ts'
+import { registerPreflightTool } from './tools/preflight.ts'
 import { registerSessionHooks } from './session-hooks.ts'
 import { registerLiveCapture } from './live.ts'
 import { installWorkingDirectoryContext } from './working-directory.ts'
@@ -71,11 +72,11 @@ export function apply(ctx: Context): void {
   registerSessionHooks(ctx)
   registerLiveCapture(ctx)
 
-  // 1. Register the 17 tools (14 original + 3 v3.0). Each registration is
-  //    isolated: one failing tool must not take down the other 16, the gate
-  //    above, or the prompt below (a partial plugin that still gates and
-  //    teaches the workflow beats an aborted `apply`). Failures are logged,
-  //    never swallowed silently.
+  // 1. Register the 19 tools (14 original + 3 v3.0 + report + preflight). Each
+  //    registration is isolated: one failing tool must not take down the other
+  //    18, the gate above, or the prompt below (a partial plugin that still
+  //    gates and teaches the workflow beats an aborted `apply`). Failures are
+  //    logged, never swallowed silently.
   const toolRegistrations: Array<[string, () => void]> = [
     ['iterate_config', () => registerConfigTool(ctx)],
     ['iterate_validate', () => registerValidateTool(ctx)],
@@ -97,6 +98,8 @@ export function apply(ctx: Context): void {
     ['iterate_defense_events', () => registerDefenseEventsTool(ctx)],
     // v3.9: PR-ready / CI-ready report export
     ['iterate_report', () => registerReportTool(ctx)],
+    // v3.12: pre-run readiness check (validation/git/stale-gate/interrupted)
+    ['iterate_preflight', () => registerPreflightTool(ctx)],
   ]
   for (const [toolName, register] of toolRegistrations) {
     try {

package/src/tools/config.ts

@@ -2,7 +2,7 @@ import { join } from 'node:path'
 import { existsSync, readFileSync } from 'node:fs'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
-import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from '../config-loader.ts'
+import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec, flattenCommands } from '../config-loader.ts'
 import {
   applyConfigUpdates,
   readRawConfig,
@@ -10,6 +10,7 @@ import {
   writeConfigFile,
 } from '../config-write.ts'
 import { withProjectLock } from '../file-lock.ts'
+import { buildValidationUpdates, detectValidationCommands } from '../validation-detect.ts'
 
 /**
  * Register the `iterate_config` tool.
@@ -21,16 +22,24 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
   ctx.tools.register(
     defineTool({
       name: 'iterate_config',
-      // `read` never writes; `write` persists a config update → only read
-      // joins a parallel dispatch group.
-      isConcurrencySafe: (args) => (args as { operation?: unknown }).operation !== 'write',
+      // `read` never writes; `write` persists a config update. `detect` is a
+      // read UNLESS it is asked to apply the detected commands.
+      isConcurrencySafe: (args) => {
+        const a = args as { operation?: unknown; apply?: unknown }
+        return a.operation !== 'write' && !(a.operation === 'detect' && a.apply === true)
+      },
       // Pending-call card: a config read vs a validated write.
       presentCall: (args) => {
-        const a = args as { operation?: unknown; section?: unknown }
-        const isWrite = a.operation === 'write'
+        const a = args as { operation?: unknown; section?: unknown; apply?: unknown }
+        const isWrite = a.operation === 'write' || (a.operation === 'detect' && a.apply === true)
+        const title = isWrite
+          ? 'Update iterate.config.yaml'
+          : a.operation === 'detect'
+            ? 'Detect validation commands'
+            : 'Read iterate.config.yaml'
         return {
           card: 'generic',
-          title: isWrite ? 'Update iterate.config.yaml' : 'Read iterate.config.yaml',
+          title,
           kind: isWrite ? 'edit' : 'read',
           ...(typeof a.section === 'string' && a.section ? { rawInput: { section: a.section } } : {}),
         }
@@ -39,13 +48,17 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
         'Read or update the iterate.config.yaml configuration from the project root. ' +
         'Returns the full parsed config, a specific section, or validation errors. ' +
         'Use this to discover available dimensions, validation commands, git settings, and personalization rules, ' +
-        'or to write back validated changes (goal, dimensions, max_rounds, review, atomic, validation, git, etc.).',
+        'or to write back validated changes (goal, dimensions, max_rounds, review, atomic, validation, git, etc.). ' +
+        'operation "detect" inspects the project manifest (package.json scripts / pytest / Cargo / Go / Make) and ' +
+        'proposes a ready-to-apply validation.commands set; pass apply:true to install it in one call.',
 
       parameters: {
         operation: {
           type: 'string',
-          description: 'Default "read". "write" validates and applies a partial config update (backed up first).',
-          enum: ['read', 'write'],
+          description:
+            'Default "read". "write" validates and applies a partial config update (backed up first). ' +
+            '"detect" proposes validation commands from the project manifest.',
+          enum: ['read', 'write', 'detect'],
         },
         path: {
           type: 'string',
@@ -60,6 +73,16 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
           type: 'boolean',
           description: 'If true, validate the config schema and return any missing fields.',
         },
+        apply: {
+          type: 'boolean',
+          description:
+            'For operation "detect": when true, install the detected commands under validation.commands.default ' +
+            '(refused if commands are already configured unless force:true).',
+        },
+        force: {
+          type: 'boolean',
+          description: 'For operation "detect" with apply:true: replace an existing default command set.',
+        },
         updates: {
           type: 'json',
           description:
@@ -83,6 +106,11 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
             availableSections: { type: 'array', items: { type: 'string' } },
             operation: { type: 'string' },
             ok: { type: 'boolean' },
+            applied: { type: 'boolean' },
+            ecosystem: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            commands: { type: 'array', items: { type: 'string' } },
+            sources: { type: 'json' },
+            updates: { type: 'json' },
             backupPath: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             error: { type: 'string' },
           },
@@ -99,6 +127,81 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
         }
         const projectRoot = resolved.root
 
+        // ── Detect operation (validation-command auto-detection) ───────────
+        // Reads the project manifest and proposes a curated command set. With
+        // apply:true it installs the set under validation.commands.default in
+        // the same validated, backed-up, locked write path as operation:write.
+        if (args.operation === 'detect') {
+          const configPath = join(projectRoot, 'iterate.config.yaml')
+          const configExists = existsSync(configPath)
+          const detection = detectValidationCommands(projectRoot)
+          const updates = buildValidationUpdates(detection.commands)
+          const base = {
+            operation: 'detect',
+            found: configExists,
+            ecosystem: detection.ecosystem,
+            commands: detection.commands,
+            sources: detection.sources as unknown as JsonValue,
+            updates: updates as unknown as JsonValue,
+          }
+          if (detection.commands.length === 0) {
+            return {
+              ...base,
+              ok: false,
+              applied: false,
+              error:
+                'no validation commands detected — the project does not advertise a test/typecheck/lint/build ' +
+                'command; configure validation.commands manually',
+            }
+          }
+          if (args.apply !== true) {
+            return { ...base, ok: true, applied: false }
+          }
+          // Refuse to silently clobber a hand-tuned command set.
+          const current = loadEffectiveConfig(projectRoot).config
+          const existing = flattenCommands(current.validation?.commands)
+          if (existing.length > 0 && args.force !== true) {
+            return {
+              ...base,
+              ok: false,
+              applied: false,
+              error:
+                `validation.commands already has ${existing.length} command(s); ` +
+                'pass force:true to replace the "default" module',
+            }
+          }
+          return withProjectLock(projectRoot, 'config-write', () => {
+            let cfgBase: Record<string, unknown>
+            try {
+              cfgBase = configExists
+                ? readRawConfig(configPath)
+                : (defaultConfig() as unknown as Record<string, unknown>)
+            } catch (err) {
+              return { ...base, ok: false, applied: false, error: `failed to read config: ${String(err)}` }
+            }
+            const merged = applyConfigUpdates(cfgBase, updates)
+            const schemaErrors = validateConfig(merged)
+            if (schemaErrors.length > 0) {
+              return {
+                ...base,
+                ok: false,
+                applied: false,
+                errors: schemaErrors.map((e) => `missing/required field: ${e}`),
+              }
+            }
+            const result = writeConfigFile(projectRoot, merged)
+            if (!result.ok) return { ...base, ok: false, applied: false, error: result.error }
+            const { config } = loadEffectiveConfig(projectRoot)
+            return {
+              ...base,
+              ok: true,
+              applied: true,
+              backupPath: result.backupPath ?? null,
+              config: config as unknown as JsonValue,
+            }
+          })
+        }
+
         // ── Write operation ────────────────────────────────────────────────
         if (args.operation === 'write') {
           const updates = args.updates as Record<string, unknown> | undefined