iterate-plugin 3.12.0 → 3.13.0

package/README.md

@@ -107,7 +107,7 @@ Both modes share:
 ### UI layer (build-free client slots, v3.12: 12 tabs, bilingual)
 
 - **ConvergenceDashboard** (`conversation.input.dock`) — live round progress bar, severity stats, dimension badges, trend mini-chart above the input; normal mode also shows fix-count badges; plus a live workflow-phase chip (current phase + running/stopped) and a **task_mode indicator (code / iterate)**, now backed by the persisted transcript (`iterate_status` / `iterate_transcript` emit `taskMode`). While a run is active the dashboard switches to a running state (round + phase) instead of the static empty state, and the start buttons are hidden.
-- **ObservatoryPanel** (`conversation.input.dock`) — a **twelve-tab** runtime observatory below the input: **live activity stream** (default tab, type filter) + **F1** review threads (expand / collapse all), **F2** convergence trend (incl. the per-round comparison table: findings raised / fixed / severity mix / validation outcomes), **F3** finding locations (severity / dimension / search filter), **F4** fixes + rollback, **F5** checkpoint resume, **F6** run console, **F7** decision timeline (type / round filter + search), **F8** Quality Gate, **F9** Experience Bank, **F10** Defense Events, **F11** Preflight. Number-key shortcuts: `1`–`9` jump to F1–F9, `0` to F10, `-` back to the live stream (F11 is click-only). **F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream); when the session stream has none they distinguish "no data on disk" from "not pulled yet" and offer a **拉取磁盘快照 (pull disk snapshot)** instruction that has the model call the read-side tools and echo the `.iterate/` artifacts back into the stream. One-click JSON export of all observatory data — manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report` (download, copy fallback). **v3.9: report-export buttons** (导出报告 / 导出 SARIF, **v3.11 + 导出 JSON 报告**) render the *same shared data model* as the `iterate_report` tool — a PR-pasteable Markdown run report, a SARIF 2.1.0 log for CI / GitHub Code Scanning, and (v3.11) the complete normalized run model as machine-readable JSON. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction. **v3.12: pre-run readiness (Preflight)** — F11 renders the latest `iterate_preflight` checklist scanned from the session stream (validation commands configured / git repo / dirty tree / stale FAIL gate / interrupted checkpoint), each warn/fail row offering the exact fix instruction (configure `validation.commands`, clear the stale gate, resume the checkpoint) so the environment is repaired BEFORE a round is spent on it; the empty state offers a **运行预检** instruction that has the model call `iterate_preflight`.
+- **ObservatoryPanel** (`conversation.input.dock`) — a **twelve-tab** runtime observatory below the input: **live activity stream** (default tab, type filter) + **F1** review threads (expand / collapse all), **F2** convergence trend (incl. the per-round comparison table: findings raised / fixed / severity mix / validation outcomes), **F3** finding locations (severity / dimension / search filter), **F4** fixes + rollback, **F5** checkpoint resume, **F6** run console, **F7** decision timeline (type / round filter + search), **F8** Quality Gate, **F9** Experience Bank, **F10** Defense Events, **F11** Preflight. Number-key shortcuts: `1`–`9` jump to F1–F9, `0` to F10, `-` back to the live stream (F11 is click-only). **F8/F9/F10 are live** — they scan the session stream for the latest `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` results and render real data (PASS/FAIL chip + per-dimension score bars, experience entries with adopt buttons + client-side search, defense type-count chips + filtered event stream); when the session stream has none they distinguish "no data on disk" from "not pulled yet" and offer a **拉取磁盘快照 (pull disk snapshot)** instruction that has the model call the read-side tools and echo the `.iterate/` artifacts back into the stream. One-click JSON export of all observatory data — manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report` (download, copy fallback). **v3.9: report-export buttons** (导出报告 / 导出 SARIF, **v3.11 + 导出 JSON 报告**) render the *same shared data model* as the `iterate_report` tool — a PR-pasteable Markdown run report, a SARIF 2.1.0 log for CI / GitHub Code Scanning, and (v3.11) the complete normalized run model as machine-readable JSON. **v3.5.3: reset actions surfaced** — F5 copies an `iterate_checkpoint clear` instruction, F8 an `iterate_quality_gate clear` instruction, F10 an `iterate_defense_events clear` instruction. **v3.12: pre-run readiness (Preflight)** — F11 renders the latest `iterate_preflight` checklist scanned from the session stream (validation commands configured / git repo / dirty tree / stale FAIL gate / interrupted checkpoint), each warn/fail row offering the exact fix instruction (configure `validation.commands`, clear the stale gate, resume the checkpoint) so the environment is repaired BEFORE a round is spent on it; the empty state offers a **运行预检** instruction that has the model call `iterate_preflight`. **v3.13: the blocking validation row auto-detects commands from the project manifest and offers a one-click 「应用建议」 (copies an `iterate_config write` payload).**
 - **TriagePanel** (`conversation.chat.turnTail`) — per-finding triage with `y` (keep → fix), `n` (skip), `a` (known-intentional) keyboard shortcuts and `↑`/`↓` navigation (focus-guarded: only active while the panel has focus), filtering, batch ops (incl. select-all), localStorage persistence. **Write-back closed loop**: the primary button copies an `iterate_triage apply` instruction for the marked entries (the tool validates, dedupes, backs up, rolls back on failure); a secondary button copies the raw `known_intentional` YAML; **回读已写入条目** copies an `iterate_triage list` instruction to confirm what actually landed. Copy payloads are aligned to the target tool schemas. **v3.2: native command buttons** (approve architectural fix, trigger new round, rollback to checkpoint). **v3.3: §8 指派修复 (assign)** — one click copies an `iterate_fix` instruction carrying every in-scope finding (respecting the batch toggle).
 - **StatsCard** (`conversation.chat.turnTail`) — convergence stats, round history, trend chart and completion summary when no findings remain.
 - **iterate theme skin** (`theme.overrideTokens`) — a warm-amber 13-token `--dsw-*` override, light/dark modes, togglable in settings.
@@ -290,7 +290,7 @@ validation:
 
 ## 🔧 Registered tools (19)
 
-- `iterate_config` — read / write `iterate.config.yaml`. `operation=read` returns the full config or a named section; `operation=write` schema-validates, backs up, then merges and writes — auto rollback on failure
+- `iterate_config` — read / write `iterate.config.yaml`. `operation=read` returns the full config or a named section; `operation=write` schema-validates, backs up, then merges and writes — auto rollback on failure; **v3.13 `operation=detect` inspects the project manifest (package.json scripts / pytest / Cargo / Go / Make) and proposes a ready-to-apply `validation.commands.default` set** (`apply:true` installs it in one call, refused unless `force:true` when commands already exist)
 - `iterate_validate` — run a whitelisted validation command, return the result
 - `iterate_decision_log` — append a decision log entry (append-only, never edits old ones), stored in `.iterate/decision-log.jsonl`
 - `iterate_context` — read the `SKILL.md` / `ITERATE.md` context
@@ -308,7 +308,7 @@ validation:
 - `iterate_quality_gate` — **v3.2** read the quality certificate (`read`), or recompute + persist a fresh one (`compute`) from findings, validation results, `findingsByRound`, and `fixedByDimension`. Real per-dimension convergence rates. **v3.5: `clear` removes the persisted certificate to reset a stale gate before a fresh iteration**
 - `iterate_defense_events` — **v3.2** query defense events (list / counts), `record` a new one, or **v3.5.3 `clear` the persisted stream** so a fresh iteration starts without stale defensive data. Human-readable labels follow the project language (en / zh)
 - `iterate_report` — **v3.9** export the run as a portable report. `format:"markdown"` (default) renders a PR-pasteable report (run header, quality gate, findings, fixes, validations, defense events, experience bank); `format:"sarif"` renders a SARIF 2.1.0 log for CI / GitHub Code Scanning (one rule per review dimension, severity → error/warning/note, file+line locations, suggested fix attached). **v3.11: `format:"json"` renders the COMPLETE normalized run model as machine-readable JSON** (findings, fixes, validations, convergence, quality gate, experience bank, defense events — the lossless format for CI dashboards / PR bots). `write:true` persists it to `.iterate/report.md` / `.iterate/report.sarif` / `.iterate/report.json`; `lang` (zh | en) selects the report language. Read-only apart from the optional report file
-- `iterate_preflight` — **v3.12** read-only pre-run readiness check. Returns a structured checklist: `validation.commands` configured (an empty set means the loop cannot prove fixes — **blocking**), whether the project is a git repository, how many files are uncommitted, whether a stale FAIL quality gate is persisted, and whether an interrupted checkpoint is waiting. Each check carries structured facts (`{ id, status: pass|warn|fail, detail }`) the observatory F11 panel localizes into a sentence + offers the exact fix instruction. Never mutates config, files, or artifacts
+- `iterate_preflight` — **v3.12** read-only pre-run readiness check. Returns a structured checklist: `validation.commands` configured (an empty set means the loop cannot prove fixes — **blocking**), whether the project is a git repository, how many files are uncommitted, whether a stale FAIL quality gate is persisted, and whether an interrupted checkpoint is waiting. Each check carries structured facts (`{ id, status: pass|warn|fail, detail }`) the observatory F11 panel localizes into a sentence + offers the exact fix instruction. **v3.13: when nothing is configured, the blocking check auto-detects commands from the manifest and ships them as `suggestedCommands`/`ecosystem`/`detectedFrom`** so F11 offers a one-click 「应用建议」. Never mutates config, files, or artifacts
 
 ---
 
@@ -346,7 +346,7 @@ All runtime state lives under `.iterate/` at the project root (can be excluded v
   `0.1.7-alpha.1`, `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.1`,
   `0.2.0-rc.2`, `0.2.1-alpha.1`, `0.2.1-alpha.2`, `0.2.1-alpha.3`,
   `0.2.1-alpha.4`, `0.2.1-alpha.5`, `0.2.1-rc.1`, `0.2.1-rc.2`,
-   `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.2-alpha.2` (27 releases,
+   `0.2.1-rc.3`, `0.2.1-rc.4`, `0.2.1-rc.5`, `0.2.2-alpha.2` (28 releases,
   `0.1.1-rc.1` …
   `0.2.2-alpha.2`).
   The plugin is built against `@deepseek-ai/dsh-tools` /

package/README.zh-CN.md

@@ -106,7 +106,7 @@ dsh plugin --profile web add iterate-plugin
 ### UI 层（客户端免构建槽位，v3.12：12 个页签，双语）
 
 - **收敛看板 `ConvergenceDashboard`**（`conversation.input.dock`）— 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图；normal 模式另显示修复计数徽章；还有运行阶段芯片（当前工作流阶段 + 运行中/已结束）与 **task_mode 指示器（code / iterate）**。运行期间看板切换为"运行中"状态（显示轮次与阶段），并隐藏启动按钮。
-- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十二个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁、**F9** 经验银行、**F10** 防御事件、**F11** 开跑预检。数字键快捷键：`1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流（F11 仅点击进入）。**F8/F9/F10 为实时数据**——扫描会话流中最近一次 `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` 结果并渲染真实数据（PASS/FAIL 徽章 + 分维度评分条、经验条目（含采纳按钮 + 客户端搜索）、防御类型计数芯片 + 筛选后的事件流）；会话流中没有数据时区分"磁盘无数据"与"尚未拉取"，并提供**拉取磁盘快照**指令（让模型调用只读工具、把 `.iterate/` 产物回显进会话流）。一键导出全部观测数据为 JSON——manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report`（优先下载，失败回退复制）。**v3.9 新增报告导出按钮**（导出报告 / 导出 SARIF，**v3.11 新增导出 JSON 报告**），与 `iterate_report` 工具共用同一份数据模型——分别产出可直接粘贴进 PR 的 Markdown 运行报告、供 CI / GitHub Code Scanning 消费的 SARIF 2.1.0 日志，以及（v3.11）完整的归一化运行模型 JSON（无损格式）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。**v3.12 新增开跑预检（Preflight）**——F11 渲染会话流中最近一次 `iterate_preflight` 清单（验证命令是否配置 / 是否 Git 仓库 / 脏工作区 / 陈旧 FAIL 门禁 / 中断断点），每个 warn/fail 行都给出精确的修复指令（配置 `validation.commands`、清除陈旧门禁、恢复断点），让环境在**花掉一轮之前**就被修好；空态提供**运行预检**指令（让模型调用 `iterate_preflight`）。
+- **运行时观测台 `ObservatoryPanel`**（`conversation.input.dock`）— 输入框下方**十二个页签**运行时观测台：**实时活动流**（默认页，支持按活动类型筛选）+ **F1** 审查线程（全部展开/全部收起）、**F2** 收敛趋势（含跨轮对比表：每轮 findings / fixed / 严重度分布 / 验证结果）、**F3** 发现定位（按严重度/维度/关键词筛选）、**F4** 修复与回滚、**F5** 断点恢复、**F6** 运行控制台、**F7** 决策时间线（按类型/轮次筛选与关键词搜索）、**F8** 质量门禁、**F9** 经验银行、**F10** 防御事件、**F11** 开跑预检。数字键快捷键：`1`–`9` 跳到 F1–F9，`0` 到 F10，`-` 回实时活动流（F11 仅点击进入）。**F8/F9/F10 为实时数据**——扫描会话流中最近一次 `iterate_quality_gate` / `iterate_experience` / `iterate_defense_events` 结果并渲染真实数据（PASS/FAIL 徽章 + 分维度评分条、经验条目（含采纳按钮 + 客户端搜索）、防御类型计数芯片 + 筛选后的事件流）；会话流中没有数据时区分"磁盘无数据"与"尚未拉取"，并提供**拉取磁盘快照**指令（让模型调用只读工具、把 `.iterate/` 产物回显进会话流）。一键导出全部观测数据为 JSON——manifest + live + `qualityGate` / `experienceBank` / `defenseEvents` / `report`（优先下载，失败回退复制）。**v3.9 新增报告导出按钮**（导出报告 / 导出 SARIF，**v3.11 新增导出 JSON 报告**），与 `iterate_report` 工具共用同一份数据模型——分别产出可直接粘贴进 PR 的 Markdown 运行报告、供 CI / GitHub Code Scanning 消费的 SARIF 2.1.0 日志，以及（v3.11）完整的归一化运行模型 JSON（无损格式）。**v3.5.3 新增重置操作**：F5 复制 `iterate_checkpoint clear`、F8 复制 `iterate_quality_gate clear`、F10 复制 `iterate_defense_events clear` 指令。**v3.12 新增开跑预检（Preflight）**——F11 渲染会话流中最近一次 `iterate_preflight` 清单（验证命令是否配置 / 是否 Git 仓库 / 脏工作区 / 陈旧 FAIL 门禁 / 中断断点），每个 warn/fail 行都给出精确的修复指令（配置 `validation.commands`、清除陈旧门禁、恢复断点），让环境在**花掉一轮之前**就被修好；空态提供**运行预检**指令（让模型调用 `iterate_preflight`）。**v3.13：阻断的验证命令行自动检测项目 manifest，提供一键「应用建议」**（复制 `iterate_config` 的 `operation:"write"` 指令，携带完整 `validation.commands.default` 载荷）。
 - **Findings 分诊面板 `TriagePanel`**（`conversation.chat.turnTail`）— 逐条分诊，键盘快捷键 `y`（保留→修复）、`n`（跳过）、`a`（已知有意）与 `↑`/`↓` 移动（焦点守卫：仅面板内焦点时生效），支持筛选、批量（含一键全选所有 findings）、localStorage 持久化。**写回闭环**：主按钮复制已标记条目的 `iterate_triage apply` 指令（工具负责校验、去重、备份、失败回滚）；次按钮复制裸 `known_intentional` YAML；**回读已写入条目**复制 `iterate_triage list` 指令核对实际落盘内容。复制载荷与目标工具 schema 对齐。**v3.2：原生命令按钮**（批准架构修复、触发新一轮、回滚到断点）。
 - **收敛统计卡片 `StatsCard`**（`conversation.chat.turnTail`）— 无 findings 时显示收敛统计、历史轮次、趋势图、完成摘要。
 - **iterate 主题皮肤**（`theme.overrideTokens`）— 暖琥珀配色的 13 个 `--dsw-*` token 覆盖，明暗双模式，可在设置页开关。
@@ -289,7 +289,7 @@ validation:
 
 ## 🔧 注册工具（19 个）
 
-- `iterate_config` — 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚
+- `iterate_config` — 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚；**v3.13 新增 `operation=detect`**——读取项目 manifest（package.json 脚本 / pytest / Cargo / Go / Make），自动提出一份可直接应用的 `validation.commands.default` 命令集（`apply:true` 一键写入，已配置时需 `force:true` 才覆盖）
 - `iterate_validate` — 运行白名单验证命令，返回结果
 - `iterate_decision_log` — 追加决策日志（只追加，不改旧），存储于 `.iterate/decision-log.jsonl`
 - `iterate_context` — 读取 `SKILL.md` / `ITERATE.md` 上下文
@@ -307,7 +307,7 @@ validation:
 - `iterate_quality_gate` — **v3.2** 读取质量凭证（`read`），或基于 findings、验证结果、`findingsByRound` 与 `fixedByDimension` 重新计算并持久化一份新凭证（`compute`）。真实的逐维度收敛率。**v3.5 新增 `clear`：删除持久化的质量凭证**，用于新一轮迭代前重置陈旧的门禁
 - `iterate_defense_events` — **v3.2** 查询防御事件（list / counts），`record` 记录一条新事件，或 **v3.5.3 `clear` 清除持久化事件流**，让新一轮迭代不带陈旧防御数据起跑。可读标签跟随项目语言（en / zh）
 - `iterate_report` — **v3.9** 把本次运行导出为可移植报告。`format:"markdown"`（默认）产出可直接粘贴进 PR 的报告（运行头部、质量门禁、发现、修复、验证、防御事件、经验银行）；`format:"sarif"` 产出 SARIF 2.1.0 日志供 CI / GitHub Code Scanning 消费（每个审查维度一条规则，严重度 → error/warning/note，携带文件+行号位置与建议修复）。**v3.11：`format:"json"` 产出完整归一化运行模型为机器可读 JSON**（发现、修复、验证、收敛率、质量门禁、经验银行、防御事件——供 CI 仪表盘 / PR 机器人消费的无损格式）。`write:true` 持久化到 `.iterate/report.md` / `.iterate/report.sarif` / `.iterate/report.json`；`lang`（zh | en）选择报告语言。除可选的报告文件外均为只读
-- `iterate_preflight` — **v3.12** 开跑前只读预检。返回结构化清单：`validation.commands` 是否已配置（为空意味着本轮无法证明修复——**阻断项**）、是否 Git 仓库、多少个未提交文件、磁盘上是否残留 FAIL 质量门禁、是否有中断断点在等待。每项都携带结构化事实（`{ id, status: pass|warn|fail, detail }`），观测台 F11 面板据此本地化为一句话并给出精确修复指令。绝不修改配置、文件或产物
+- `iterate_preflight` — **v3.12** 开跑前只读预检。返回结构化清单：`validation.commands` 是否已配置（为空意味着本轮无法证明修复——**阻断项**）、是否 Git 仓库、多少个未提交文件、磁盘上是否残留 FAIL 质量门禁、是否有中断断点在等待。每项都携带结构化事实（`{ id, status: pass|warn|fail, detail }`），观测台 F11 面板据此本地化为一句话并给出精确修复指令。**v3.13：未配置时自动检测项目 manifest，把 `suggestedCommands`/`ecosystem`/`detectedFrom` 附到阻断项**，F11 据此提供一键「应用建议」。绝不修改配置、文件或产物
 
 ---
 
@@ -336,7 +336,7 @@ validation:
 ### Node.js / DSH 兼容范围
 
 - **Node.js**：`>=20`（`package.json` 的 `engines.node`）。
-- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`、`0.2.1-alpha.5`、`0.2.1-rc.1`、`0.2.1-rc.2`、`0.2.1-rc.3`、`0.2.1-rc.4`、`0.2.2-alpha.2`（共 27 个版本，`0.1.1-rc.1` … `0.2.2-alpha.2`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.2-alpha.2` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch，以及 v3.9 起的会话状态记录接口）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.2-alpha.2 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
+- **DSH**：`package.json` 的 `dsh.compatibility.dshReleases` 字段是发布兼容性的**唯一真源**（本 README 逐字镜像该字段；两者需同步更新）。以下官方版本声明为 `compatible`：`0.1.1-rc.1`、`0.1.2-alpha.4`、`0.1.2-alpha.5`、`0.1.2-rc.1`、`0.1.3-alpha.1`、`0.1.5-alpha.1`、`0.1.5-alpha.2`、`0.1.5-rc.1`、`0.1.5-rc.2`、`0.1.6-alpha.1`、`0.1.6-alpha.2`、`0.1.7-alpha.1`、`0.1.7-alpha.2`、`0.1.7-rc.1`、`0.1.7-rc.2`、`0.2.0-rc.1`、`0.2.0-rc.2`、`0.2.1-alpha.1`、`0.2.1-alpha.2`、`0.2.1-alpha.3`、`0.2.1-alpha.4`、`0.2.1-alpha.5`、`0.2.1-rc.1`、`0.2.1-rc.2`、`0.2.1-rc.3`、`0.2.1-rc.4`、`0.2.1-rc.5`、`0.2.2-alpha.2`（共 28 个版本，`0.1.1-rc.1` … `0.2.2-alpha.2`）。插件基于 `@deepseek-ai/dsh-tools` / `@deepseek-ai/dsh-util-values` `0.2.2-alpha.2` 构建，只使用公开契约（工具注册、客户端 slots + theme、bundle patch，以及 v3.9 起的会话状态记录接口）。插件同时声明 `engines.dsh`（`>=0.1.1-rc.1`），使 dsh ≥ 0.2.2-alpha.2 运行时只依据该范围判断兼容性（更早的运行时仍回退校验 `package.json` 中列出的 `@deepseek-ai/dsh-*` peer 版本）。
 - **一次性 Profile 证据（真实，`dsh` CLI `0.1.1-rc.1`）**：在临时 `$DSH_HOME` 下
   `dsh plugin --profile <p> add <本仓库>` 约 449ms 完成安装；`dsh --profile <p>
   --dump-config` 正确合成 `iterate-plugin` bundle patch；`dsh plugin --profile <p>

package/dist/tools/config.js

@@ -1,9 +1,10 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec } from "../config-loader.js";
+import { defaultConfig, loadEffectiveConfig, validateConfig, resolveProjectRootForExec, flattenCommands } from "../config-loader.js";
 import { applyConfigUpdates, readRawConfig, validateConfigUpdates, writeConfigFile, } from "../config-write.js";
 import { withProjectLock } from "../file-lock.js";
+import { buildValidationUpdates, detectValidationCommands } from "../validation-detect.js";
 /**
  * Register the `iterate_config` tool.
  * Reads and returns the iterate.config.yaml configuration, or writes a
@@ -13,16 +14,24 @@ import { withProjectLock } from "../file-lock.js";
 export function registerConfigTool(ctx) {
     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.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;
+            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;
-            const isWrite = a.operation === 'write';
+            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 } } : {}),
             };
@@ -30,12 +39,15 @@ export function registerConfigTool(ctx) {
         description: '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',
@@ -49,6 +61,15 @@ export function registerConfigTool(ctx) {
                 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: 'For operation "write": a partial config object to merge in, e.g. ' +
@@ -70,6 +91,11 @@ export function registerConfigTool(ctx) {
                     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' },
                 },
@@ -84,6 +110,80 @@ export function registerConfigTool(ctx) {
                 return { found: false, error: resolved.reason };
             }
             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,
+                    updates: updates,
+                };
+                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;
+                    try {
+                        cfgBase = configExists
+                            ? readRawConfig(configPath)
+                            : defaultConfig();
+                    }
+                    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,
+                    };
+                });
+            }
             // ── Write operation ────────────────────────────────────────────────
             if (args.operation === 'write') {
                 const updates = args.updates;

package/dist/tools/preflight.js

@@ -23,6 +23,7 @@ import { readCheckpoint, computeStatus } from "./checkpoint.js";
 import { readDecisionEntries } from "./decision-log.js";
 import { readRegistry } from "./fix.js";
 import { resultHeadline } from "./present.js";
+import { detectValidationCommands } from "../validation-detect.js";
 /**
  * Build the readiness checklist from already-gathered facts (pure).
  *
@@ -44,11 +45,23 @@ import { resultHeadline } from "./present.js";
  *                                progressed; `warn` + resume or clear.
  */
 export function buildPreflightReport(input) {
+    const suggestions = Array.isArray(input.suggestedCommands) ? input.suggestedCommands.filter((c) => typeof c === 'string' && c.length > 0) : [];
     const checks = [
         {
             id: 'validation',
             status: input.validationCommandCount > 0 ? 'pass' : 'fail',
-            detail: { commandCount: input.validationCommandCount },
+            detail: {
+                commandCount: input.validationCommandCount,
+                // Only meaningful when the blocking case is hit; the client turns these
+                // into a one-click "apply detected commands" action.
+                ...(input.validationCommandCount === 0 && suggestions.length > 0
+                    ? {
+                        suggestedCommands: suggestions,
+                        ecosystem: input.ecosystem ?? null,
+                        detectedFrom: Array.isArray(input.detectedFrom) ? input.detectedFrom : [],
+                    }
+                    : {}),
+            },
         },
         {
             id: 'git',
@@ -80,9 +93,16 @@ function describeCheck(id, detail) {
     switch (id) {
         case 'validation': {
             const n = Number(detail.commandCount ?? 0);
-            return n > 0
-                ? `${n} validation command(s) configured`
-                : 'no validation.commands configured — the run cannot prove fixes (blocking)';
+            if (n > 0)
+                return `${n} validation command(s) configured`;
+            const suggested = Array.isArray(detail.suggestedCommands)
+                ? detail.suggestedCommands.map((c) => String(c))
+                : [];
+            if (suggested.length > 0) {
+                return ('no validation.commands configured — the run cannot prove fixes (blocking); ' +
+                    `detected ${String(detail.ecosystem ?? 'project')} commands: ${suggested.join(', ')}`);
+            }
+            return 'no validation.commands configured — the run cannot prove fixes (blocking)';
         }
         case 'git':
             return detail.isRepo === true
@@ -180,6 +200,24 @@ export function registerPreflightTool(ctx) {
             catch {
                 validationCommandCount = 0;
             }
+            // 1b. When nothing is configured, inspect the project manifest so the
+            //     blocking check ships with an actionable, ready-to-apply set.
+            let suggestedCommands = [];
+            let detectedEcosystem = null;
+            let detectedFrom = [];
+            if (validationCommandCount === 0) {
+                try {
+                    const detection = detectValidationCommands(projectRoot);
+                    suggestedCommands = detection.commands;
+                    detectedEcosystem = detection.ecosystem;
+                    detectedFrom = detection.sources.map((s) => s.file);
+                }
+                catch {
+                    suggestedCommands = [];
+                    detectedEcosystem = null;
+                    detectedFrom = [];
+                }
+            }
             // 2/3. git repo + dirty tree (best-effort; any failure degrades to unknown).
             let isGitRepo = false;
             let changedFiles = null;
@@ -232,6 +270,9 @@ export function registerPreflightTool(ctx) {
                 gateOverallStatus,
                 interrupted,
                 resumeCount,
+                suggestedCommands,
+                ecosystem: detectedEcosystem,
+                detectedFrom,
             });
             return { ...report, checks: report.checks };
         },

package/dist/validation-detect.js

@@ -0,0 +1,193 @@
+/**
+ * src/validation-detect.ts — detect a project's validation commands.
+ *
+ * Why it exists: the iterate loop is fail-closed on `validation.commands` — an
+ * empty set means it cannot tell a fix from a regression, so `iterate_preflight`
+ * blocks the run. Until now the only remedy was to hand-write the YAML, which is
+ * error-prone (wrong nesting, wrong module key, commands the project does not
+ * actually expose). This module inspects the project's own manifest files and
+ * proposes a small, curated command set that the config tool can apply in one
+ * call.
+ *
+ * Detection is advisory and read-only: it only proposes commands the project's
+ * manifest actually advertises (package.json scripts, pytest/ruff/mypy config,
+ * Cargo, Go, Make targets). It never invents a command and never executes one.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Hard cap so a project with many scripts cannot flood the config. */
+const MAX_COMMANDS = 6;
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function readJsonObject(path) {
+    const text = readText(path);
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        // A JSON array / scalar is not a manifest object — treat it as absent.
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function existsFile(root, name) {
+    try {
+        return existsSync(join(root, name));
+    }
+    catch {
+        return false;
+    }
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/** Node: only scripts the manifest explicitly defines, in a curated order. */
+function detectNode(root, add) {
+    const pkg = readJsonObject(join(root, 'package.json'));
+    if (!pkg)
+        return false;
+    const scripts = asRecord(pkg.scripts);
+    const has = (name) => typeof scripts[name] === 'string' && scripts[name].trim().length > 0;
+    // test/typecheck/lint/build are the four signals that actually prove a change
+    // is sound. Arbitrary user scripts are intentionally NOT auto-run.
+    if (has('test'))
+        add('npm test', 'package.json', 'scripts.test');
+    if (has('typecheck'))
+        add('npm run typecheck', 'package.json', 'scripts.typecheck');
+    if (has('lint'))
+        add('npm run lint', 'package.json', 'scripts.lint');
+    if (has('build'))
+        add('npm run build', 'package.json', 'scripts.build');
+    return true;
+}
+/** Python: pytest plus configured ruff / mypy. A bare pyproject is not pytest. */
+function detectPython(root, add) {
+    const pyproject = readText(join(root, 'pyproject.toml'));
+    const setupCfg = readText(join(root, 'setup.cfg'));
+    const pytestIni = existsFile(root, 'pytest.ini');
+    const toxIni = existsFile(root, 'tox.ini');
+    const testsDir = existsFile(root, 'tests');
+    const pyprojectPytest = pyproject !== null && /\[tool\.pytest/.test(pyproject);
+    const setupCfgPytest = setupCfg !== null && /\[tool:pytest\]/.test(setupCfg);
+    const matched = pyproject !== null || setupCfg !== null || pytestIni || toxIni || testsDir;
+    if (!matched)
+        return false;
+    if (pytestIni)
+        add('pytest -q', 'pytest.ini', 'pytest');
+    else if (toxIni)
+        add('pytest -q', 'tox.ini', 'pytest');
+    else if (pyprojectPytest)
+        add('pytest -q', 'pyproject.toml', 'tool.pytest');
+    else if (setupCfgPytest)
+        add('pytest -q', 'setup.cfg', 'tool:pytest');
+    else if (testsDir)
+        add('pytest -q', 'tests', 'tests-dir');
+    if (pyproject !== null && /\[tool\.ruff/.test(pyproject))
+        add('ruff check .', 'pyproject.toml', 'tool.ruff');
+    if (pyproject !== null && /\[tool\.mypy\]/.test(pyproject))
+        add('mypy .', 'pyproject.toml', 'tool.mypy');
+    return true;
+}
+/** Rust: cargo test, plus clippy/rustfmt when the project configures them. */
+function detectRust(root, add) {
+    if (!existsFile(root, 'Cargo.toml'))
+        return false;
+    add('cargo test', 'Cargo.toml', 'cargo.test');
+    if (existsFile(root, 'clippy.toml') || existsFile(root, '.clippy.toml')) {
+        add('cargo clippy --all-targets -- -D warnings', 'clippy.toml', 'cargo.clippy');
+    }
+    if (existsFile(root, 'rustfmt.toml') || existsFile(root, '.rustfmt.toml')) {
+        add('cargo fmt --check', 'rustfmt.toml', 'cargo.fmt');
+    }
+    return true;
+}
+/** Go: test + vet are the two checks a go module always supports. */
+function detectGo(root, add) {
+    if (!existsFile(root, 'go.mod'))
+        return false;
+    add('go test ./...', 'go.mod', 'go.test');
+    add('go vet ./...', 'go.mod', 'go.vet');
+    return true;
+}
+/** Make: the generic fallback, only when no ecosystem-specific command exists. */
+function detectMake(root, add) {
+    const makefile = ['Makefile', 'makefile', 'GNUmakefile'].find((name) => existsFile(root, name));
+    if (!makefile)
+        return false;
+    const text = readText(join(root, makefile)) ?? '';
+    const targets = new Set();
+    for (const line of text.split(/\r?\n/)) {
+        // `target:`, but NOT a `VAR := value` / `VAR = value` assignment. The
+        // lookahead has to skip the optional space before `=` (`test := nope`).
+        const match = /^([A-Za-z0-9_.-]+)\s*:(?!=|\s*=)/.exec(line);
+        if (match)
+            targets.add(match[1]);
+    }
+    if (targets.has('test'))
+        add('make test', makefile, 'target.test');
+    if (targets.has('check'))
+        add('make check', makefile, 'target.check');
+    return true;
+}
+/**
+ * Inspect `projectRoot` and return a curated, ordered validation-command set.
+ *
+ * Never throws: unreadable or malformed manifests simply contribute nothing.
+ * The returned `commands` and `sources` always have the same length.
+ */
+export function detectValidationCommands(projectRoot) {
+    const commands = [];
+    const sources = [];
+    const seen = new Set();
+    const add = (command, file, reason) => {
+        if (commands.length >= MAX_COMMANDS)
+            return;
+        if (seen.has(command))
+            return;
+        seen.add(command);
+        commands.push(command);
+        sources.push({ file, reason });
+    };
+    let ecosystem = null;
+    const run = (name, detect) => {
+        const before = commands.length;
+        let matched = false;
+        try {
+            matched = detect(add);
+        }
+        catch {
+            matched = false;
+        }
+        if (matched && commands.length > before && ecosystem === null)
+            ecosystem = name;
+    };
+    run('node', (a) => detectNode(projectRoot, a));
+    run('python', (a) => detectPython(projectRoot, a));
+    run('rust', (a) => detectRust(projectRoot, a));
+    run('go', (a) => detectGo(projectRoot, a));
+    // Make is the generic wrapper: only consult it when nothing else produced a
+    // command, so a Makefile that just calls `npm test` does not double-report.
+    if (commands.length === 0)
+        run('make', (a) => detectMake(projectRoot, a));
+    return { ecosystem, commands, sources };
+}
+/**
+ * Build the partial config update that installs a detected command set under
+ * the `default` module. The config tool deep-merges this into an existing
+ * `validation.commands` map, so other modules are preserved.
+ */
+export function buildValidationUpdates(commands) {
+    return { validation: { commands: { default: [...commands] } } };
+}

package/lib/client.js

@@ -1,4 +1,4 @@
-/* iterate-plugin client source-digest: 408ff45e22a5041e34cdeb7ccd786225658f6c1fe52a7bb5233fc35450546683 */
+/* iterate-plugin client source-digest: 909db487a440ae131a6de59f253a9d84b240e5fbd55bce9ae83a9876b711a9a2 */
 window.__ModuleLoader__.load({ id: "iterate-plugin", factory: (require) => {
 var module = { exports: {} };
 var exports = module.exports;
@@ -1343,6 +1343,18 @@ function buildPreflightInstruction() {
 ${JSON.stringify({}, null, 2)}
 \`\`\``;
 }
+function buildValidationApplyInstruction(commands) {
+  const list = Array.isArray(commands) ? commands.filter((c) => typeof c === "string" && c.length > 0) : [];
+  const payload = {
+    operation: "write",
+    updates: { validation: { commands: { default: list } } }
+  };
+  return `\u8BF7\u8C03\u7528 \`iterate_config\` \u628A\u68C0\u6D4B\u5230\u7684\u9A8C\u8BC1\u547D\u4EE4\u5199\u5165 \`validation.commands.default\`\uFF08\u4F1A\u5148\u5907\u4EFD\u914D\u7F6E\uFF09\uFF1A
+
+\`\`\`json
+${JSON.stringify(payload, null, 2)}
+\`\`\``;
+}
 function buildRollbackInstruction(id) {
   return `\u8BF7\u8C03\u7528 \`iterate_rollback\` \u56DE\u6EDA\u4EE5\u4E0B\u4FEE\u590D\uFF1A
 
@@ -2755,6 +2767,7 @@ var EN = {
   \u590D\u5236\u9884\u68C0\u6307\u4EE4: "Copy preflight instruction",
   \u9A8C\u8BC1\u547D\u4EE4: "Validation commands",
   "\u5DF2\u914D\u7F6E {a0} \u6761\u9A8C\u8BC1\u547D\u4EE4": "{a0} validation command(s) configured",
+  "\u672A\u914D\u7F6E validation.commands\uFF08\u963B\u65AD\u9879\uFF09\u2014\u2014 \u68C0\u6D4B\u5230 {a0} \u9879\u76EE\uFF0C\u5EFA\u8BAE\uFF1A{a1}": "validation.commands is not configured (blocking) \u2014 detected {a0} project; suggested: {a1}",
   "\u672A\u914D\u7F6E validation.commands \u2014\u2014 \u672C\u8F6E\u65E0\u6CD5\u8BC1\u660E\u4FEE\u590D\uFF0C\u5C5E\u963B\u65AD\u9879": "validation.commands is not configured \u2014 the run cannot prove fixes (blocking)",
   "Git \u4ED3\u5E93": "Git repository",
   "\u5DF2\u68C0\u6D4B\u5230 Git \u4ED3\u5E93": "Git repository detected",
@@ -2771,6 +2784,7 @@ var EN = {
   "\u5B58\u5728\u4E2D\u65AD\u65AD\u70B9\uFF08\u5DF2\u6062\u590D {a0} \u6B21\uFF09\u2014\u2014 \u6062\u590D\u6216\u6E05\u9664\u540E\u518D\u5F00\u8DD1": "An interrupted checkpoint is waiting (resumed {a0}x) \u2014 resume or clear it first",
   \u65E0\u4E2D\u65AD\u65AD\u70B9: "No interrupted checkpoint",
   \u914D\u7F6E\u9A8C\u8BC1\u547D\u4EE4: "Configure validation",
+  \u5E94\u7528\u5EFA\u8BAE: "Apply suggestion",
   \u6062\u590D\u65AD\u70B9: "Resume checkpoint",
   "\u963B\u65AD {a0} \xB7 \u8B66\u544A {a1}": "Blocking {a0} \xB7 warnings {a1}",
   "\u9884\u68C0\u5931\u8D25\uFF1A{a0}": "Preflight failed: {a0}",
@@ -5797,7 +5811,15 @@ function ObservatoryPanel(props) {
         label: t("\u9A8C\u8BC1\u547D\u4EE4"),
         detail: (d) => {
           const n = Number(d.commandCount ?? 0);
-          return n > 0 ? tf("\u5DF2\u914D\u7F6E {a0} \u6761\u9A8C\u8BC1\u547D\u4EE4", { a0: n }) : t("\u672A\u914D\u7F6E validation.commands \u2014\u2014 \u672C\u8F6E\u65E0\u6CD5\u8BC1\u660E\u4FEE\u590D\uFF0C\u5C5E\u963B\u65AD\u9879");
+          if (n > 0) return tf("\u5DF2\u914D\u7F6E {a0} \u6761\u9A8C\u8BC1\u547D\u4EE4", { 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("\u672A\u914D\u7F6E validation.commands\uFF08\u963B\u65AD\u9879\uFF09\u2014\u2014 \u68C0\u6D4B\u5230 {a0} \u9879\u76EE\uFF0C\u5EFA\u8BAE\uFF1A{a1}", {
+              a0: String(d.ecosystem || ""),
+              a1: suggested.join(" \xB7 ")
+            });
+          }
+          return t("\u672A\u914D\u7F6E validation.commands \u2014\u2014 \u672C\u8F6E\u65E0\u6CD5\u8BC1\u660E\u4FEE\u590D\uFF0C\u5C5E\u963B\u65AD\u9879");
         }
       },
       git: {
@@ -5832,10 +5854,19 @@ function ObservatoryPanel(props) {
         }
       }
     };
-    const fixFor = (id) => {
+    const fixFor = (id, detail) => {
       switch (id) {
-        case "validation":
+        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("\u5E94\u7528\u5EFA\u8BAE"),
+              instruction: buildValidationApplyInstruction(suggested)
+            };
+          }
           return { key: "preflight-fix-validation", label: t("\u914D\u7F6E\u9A8C\u8BC1\u547D\u4EE4"), instruction: buildConfigFieldInstruction("validation.commands") };
+        }
         case "stale-gate":
           return { key: "preflight-fix-gate", label: t("\u6E05\u9664\u95E8\u7981"), instruction: buildQualityGateClearInstruction() };
         case "interrupted-checkpoint":
@@ -5849,14 +5880,14 @@ function ObservatoryPanel(props) {
       const status = String(c.status || "warn");
       const meta = CHECK_META[id];
       const label = meta ? meta.label : id || "?";
-      const detail = meta ? meta.detail(c.detail || {}) : "";
-      const fix = status !== "pass" ? fixFor(id) : null;
+      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" }, detail),
+        React.createElement("span", { className: "iterate-obs-msg" }, detailText),
         fix ? React.createElement("button", {
           className: "iterate-btn",
           "data-copied": copiedKey === fix.key ? "" : void 0,

package/lib/parse.js

@@ -1954,6 +1954,30 @@ export function buildPreflightInstruction() {
   )
 }
 
+/**
+ * `iterate_config` write instruction that installs the validation commands the
+ * preflight panel detected. Copies the exact command set the user saw, so the
+ * model applies it deterministically instead of re-detecting (and drifting).
+ *
+ * @param {string[]} commands
+ * @returns {string}
+ */
+export function buildValidationApplyInstruction(commands) {
+  const list = Array.isArray(commands)
+    ? commands.filter((c) => typeof c === 'string' && c.length > 0)
+    : []
+  const payload = {
+    operation: 'write',
+    updates: { validation: { commands: { default: list } } },
+  }
+  return (
+    '请调用 `iterate_config` 把检测到的验证命令写入 `validation.commands.default`（会先备份配置）：\n\n' +
+    '```json\n' +
+    `${JSON.stringify(payload, null, 2)}\n` +
+    '```'
+  )
+}
+
 /**
  * `iterate_rollback` payload for one applied fix id.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterate-plugin",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness with quality command center and experience bank (v3.3). Features: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus dry-run pure-review mode, quality gate compute/persist, writable experience bank, defense events stream (record + bilingual labels), and native command buttons — with a live quality command center (F8/F9/F10 render real session data), §8 assign-fix instruction, and task_mode indicator wired end to end.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,7 @@
         "0.2.1-rc.2": "compatible",
         "0.2.1-rc.3": "compatible",
         "0.2.1-rc.4": "compatible",
+        "0.2.1-rc.5": "compatible",
         "0.2.2-alpha.2": "compatible"
       }
     },
@@ -96,9 +97,9 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5-alpha.2 || ~4.0.6-alpha.1",
-    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.2-alpha.2",
-    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.2-alpha.2"
+    "@deepseek-ai/dsh-session": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.1 || 0.1.2-alpha.4 || 0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.1.2-alpha.5 || 0.1.2-rc.1 || 0.1.5-alpha.1 || 0.1.5-alpha.2 || 0.1.5-rc.1 || 0.1.5-rc.2 || 0.1.6-alpha.1 || 0.1.6-alpha.2 || 0.1.7-alpha.1 || 0.1.7-alpha.2 || 0.1.7-rc.1 || 0.1.7-rc.2 || 0.2.0-rc.1 || 0.2.0-rc.2 || 0.2.1-alpha.1 || 0.2.1-alpha.2 || 0.2.1-alpha.3 || 0.2.1-alpha.4 || 0.2.1-alpha.5 || 0.2.1-rc.1 || 0.2.1-rc.2 || 0.2.1-rc.3 || 0.2.1-rc.4 || 0.2.1-rc.5 || 0.2.2-alpha.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {

package/src/client/i18n.ts

@@ -460,6 +460,8 @@ export const EN: Record<string, string> = {
   复制预检指令: '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',
@@ -481,6 +483,7 @@ export const EN: Record<string, string> = {
     '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}',

package/src/client/index.ts

@@ -77,6 +77,7 @@ import {
   scanSessionForDefenseEvents,
   scanSessionForPreflight,
   buildPreflightInstruction,
+  buildValidationApplyInstruction,
   filterLiveEntries,
   filterTimelineEntries,
   serializeObservatoryExport,
@@ -3464,9 +3465,17 @@ function ObservatoryPanel(props: SlotProps) {
         label: t('验证命令'),
         detail: (d) => {
           const n = Number(d.commandCount ?? 0)
-          return n > 0
-            ? tf('已配置 {a0} 条验证命令', { a0: n })
-            : t('未配置 validation.commands —— 本轮无法证明修复，属阻断项')
+          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: {
@@ -3505,10 +3514,21 @@ function ObservatoryPanel(props: SlotProps) {
     }
 
     // Repair action per check id; null = guidance only (no tool can fix it).
-    const fixFor = (id: string): { key: string; label: string; instruction: string } | null => {
+    const fixFor = (id: string, detail: Record<string, unknown>): { key: string; label: string; instruction: string } | null => {
       switch (id) {
-        case 'validation':
+        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':
@@ -3523,12 +3543,12 @@ function ObservatoryPanel(props: SlotProps) {
       const status = String(c.status || 'warn')
       const meta = CHECK_META[id]
       const label = meta ? meta.label : id || '?'
-      const detail = meta ? meta.detail(c.detail || {}) : ''
-      const fix = status !== 'pass' ? fixFor(id) : null
+      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' }, detail),
+        React.createElement('span', { className: 'iterate-obs-msg' }, detailText),
         fix
           ? React.createElement('button', {
               className: 'iterate-btn', 'data-copied': copiedKey === fix.key ? '' : undefined,

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

package/src/tools/preflight.ts

@@ -25,6 +25,7 @@ import { readCheckpoint, computeStatus } from './checkpoint.ts'
 import { readDecisionEntries } from './decision-log.ts'
 import { readRegistry } from './fix.ts'
 import { resultHeadline } from './present.ts'
+import { detectValidationCommands } from '../validation-detect.ts'
 
 /** A single check's outcome. `fail` blocks a clean run; `warn` is advisory. */
 export type PreflightStatus = 'pass' | 'warn' | 'fail'
@@ -65,6 +66,12 @@ export interface PreflightInput {
   interrupted: boolean
   /** How many times the leftover checkpoint has already been resumed. */
   resumeCount: number
+  /** Commands auto-detected from the project manifest (only when none are configured). */
+  suggestedCommands?: string[]
+  /** Ecosystem that produced the suggestions (node/python/rust/go/make). */
+  ecosystem?: string | null
+  /** Manifest files the suggestions were derived from. */
+  detectedFrom?: string[]
 }
 
 /**
@@ -88,11 +95,23 @@ export interface PreflightInput {
  *                                progressed; `warn` + resume or clear.
  */
 export function buildPreflightReport(input: PreflightInput): PreflightReport {
+  const suggestions = Array.isArray(input.suggestedCommands) ? input.suggestedCommands.filter((c) => typeof c === 'string' && c.length > 0) : []
   const checks: PreflightCheck[] = [
     {
       id: 'validation',
       status: input.validationCommandCount > 0 ? 'pass' : 'fail',
-      detail: { commandCount: input.validationCommandCount },
+      detail: {
+        commandCount: input.validationCommandCount,
+        // Only meaningful when the blocking case is hit; the client turns these
+        // into a one-click "apply detected commands" action.
+        ...(input.validationCommandCount === 0 && suggestions.length > 0
+          ? {
+              suggestedCommands: suggestions,
+              ecosystem: input.ecosystem ?? null,
+              detectedFrom: Array.isArray(input.detectedFrom) ? input.detectedFrom : [],
+            }
+          : {}),
+      },
     },
     {
       id: 'git',
@@ -126,9 +145,17 @@ function describeCheck(id: string, detail: Record<string, unknown>): string {
   switch (id) {
     case 'validation': {
       const n = Number(detail.commandCount ?? 0)
-      return n > 0
-        ? `${n} validation command(s) configured`
-        : 'no validation.commands configured — the run cannot prove fixes (blocking)'
+      if (n > 0) return `${n} validation command(s) configured`
+      const suggested = Array.isArray(detail.suggestedCommands)
+        ? detail.suggestedCommands.map((c) => String(c))
+        : []
+      if (suggested.length > 0) {
+        return (
+          'no validation.commands configured — the run cannot prove fixes (blocking); ' +
+          `detected ${String(detail.ecosystem ?? 'project')} commands: ${suggested.join(', ')}`
+        )
+      }
+      return 'no validation.commands configured — the run cannot prove fixes (blocking)'
     }
     case 'git':
       return detail.isRepo === true
@@ -229,6 +256,24 @@ export function registerPreflightTool(ctx: { tools: { register: (def: ReturnType
           validationCommandCount = 0
         }
 
+        // 1b. When nothing is configured, inspect the project manifest so the
+        //     blocking check ships with an actionable, ready-to-apply set.
+        let suggestedCommands: string[] = []
+        let detectedEcosystem: string | null = null
+        let detectedFrom: string[] = []
+        if (validationCommandCount === 0) {
+          try {
+            const detection = detectValidationCommands(projectRoot)
+            suggestedCommands = detection.commands
+            detectedEcosystem = detection.ecosystem
+            detectedFrom = detection.sources.map((s) => s.file)
+          } catch {
+            suggestedCommands = []
+            detectedEcosystem = null
+            detectedFrom = []
+          }
+        }
+
         // 2/3. git repo + dirty tree (best-effort; any failure degrades to unknown).
         let isGitRepo = false
         let changedFiles: number | null = null
@@ -281,6 +326,9 @@ export function registerPreflightTool(ctx: { tools: { register: (def: ReturnType
           gateOverallStatus,
           interrupted,
           resumeCount,
+          suggestedCommands,
+          ecosystem: detectedEcosystem,
+          detectedFrom,
         })
         return { ...report, checks: report.checks as unknown as JsonValue }
       },

package/src/validation-detect.ts

@@ -0,0 +1,207 @@
+/**
+ * src/validation-detect.ts — detect a project's validation commands.
+ *
+ * Why it exists: the iterate loop is fail-closed on `validation.commands` — an
+ * empty set means it cannot tell a fix from a regression, so `iterate_preflight`
+ * blocks the run. Until now the only remedy was to hand-write the YAML, which is
+ * error-prone (wrong nesting, wrong module key, commands the project does not
+ * actually expose). This module inspects the project's own manifest files and
+ * proposes a small, curated command set that the config tool can apply in one
+ * call.
+ *
+ * Detection is advisory and read-only: it only proposes commands the project's
+ * manifest actually advertises (package.json scripts, pytest/ruff/mypy config,
+ * Cargo, Go, Make targets). It never invents a command and never executes one.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Ecosystems this module knows how to read a manifest for. */
+export type Ecosystem = 'node' | 'python' | 'rust' | 'go' | 'make'
+
+/** One manifest fact that produced a command. */
+export interface DetectionSource {
+  /** Manifest file, relative to the project root. */
+  file: string
+  /** Short machine-stable reason, e.g. `scripts.test`. */
+  reason: string
+}
+
+/** The result of inspecting a project root. */
+export interface ValidationDetection {
+  /** The ecosystem that produced the first command, or null when none matched. */
+  ecosystem: Ecosystem | null
+  /** Ordered, de-duplicated commands for `validation.commands.default`. */
+  commands: string[]
+  /** One entry per command, same order/length as `commands`. */
+  sources: DetectionSource[]
+}
+
+/** Hard cap so a project with many scripts cannot flood the config. */
+const MAX_COMMANDS = 6
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf-8')
+  } catch {
+    return null
+  }
+}
+
+function readJsonObject(path: string): Record<string, unknown> | null {
+  const text = readText(path)
+  if (text === null) return null
+  try {
+    const parsed: unknown = JSON.parse(text)
+    // A JSON array / scalar is not a manifest object — treat it as absent.
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null
+  } catch {
+    return null
+  }
+}
+
+function existsFile(root: string, name: string): boolean {
+  try {
+    return existsSync(join(root, name))
+  } catch {
+    return false
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {}
+}
+
+type AddCommand = (command: string, file: string, reason: string) => void
+
+/** Node: only scripts the manifest explicitly defines, in a curated order. */
+function detectNode(root: string, add: AddCommand): boolean {
+  const pkg = readJsonObject(join(root, 'package.json'))
+  if (!pkg) return false
+  const scripts = asRecord(pkg.scripts)
+  const has = (name: string): boolean =>
+    typeof scripts[name] === 'string' && (scripts[name] as string).trim().length > 0
+  // test/typecheck/lint/build are the four signals that actually prove a change
+  // is sound. Arbitrary user scripts are intentionally NOT auto-run.
+  if (has('test')) add('npm test', 'package.json', 'scripts.test')
+  if (has('typecheck')) add('npm run typecheck', 'package.json', 'scripts.typecheck')
+  if (has('lint')) add('npm run lint', 'package.json', 'scripts.lint')
+  if (has('build')) add('npm run build', 'package.json', 'scripts.build')
+  return true
+}
+
+/** Python: pytest plus configured ruff / mypy. A bare pyproject is not pytest. */
+function detectPython(root: string, add: AddCommand): boolean {
+  const pyproject = readText(join(root, 'pyproject.toml'))
+  const setupCfg = readText(join(root, 'setup.cfg'))
+  const pytestIni = existsFile(root, 'pytest.ini')
+  const toxIni = existsFile(root, 'tox.ini')
+  const testsDir = existsFile(root, 'tests')
+  const pyprojectPytest = pyproject !== null && /\[tool\.pytest/.test(pyproject)
+  const setupCfgPytest = setupCfg !== null && /\[tool:pytest\]/.test(setupCfg)
+  const matched = pyproject !== null || setupCfg !== null || pytestIni || toxIni || testsDir
+  if (!matched) return false
+
+  if (pytestIni) add('pytest -q', 'pytest.ini', 'pytest')
+  else if (toxIni) add('pytest -q', 'tox.ini', 'pytest')
+  else if (pyprojectPytest) add('pytest -q', 'pyproject.toml', 'tool.pytest')
+  else if (setupCfgPytest) add('pytest -q', 'setup.cfg', 'tool:pytest')
+  else if (testsDir) add('pytest -q', 'tests', 'tests-dir')
+
+  if (pyproject !== null && /\[tool\.ruff/.test(pyproject)) add('ruff check .', 'pyproject.toml', 'tool.ruff')
+  if (pyproject !== null && /\[tool\.mypy\]/.test(pyproject)) add('mypy .', 'pyproject.toml', 'tool.mypy')
+  return true
+}
+
+/** Rust: cargo test, plus clippy/rustfmt when the project configures them. */
+function detectRust(root: string, add: AddCommand): boolean {
+  if (!existsFile(root, 'Cargo.toml')) return false
+  add('cargo test', 'Cargo.toml', 'cargo.test')
+  if (existsFile(root, 'clippy.toml') || existsFile(root, '.clippy.toml')) {
+    add('cargo clippy --all-targets -- -D warnings', 'clippy.toml', 'cargo.clippy')
+  }
+  if (existsFile(root, 'rustfmt.toml') || existsFile(root, '.rustfmt.toml')) {
+    add('cargo fmt --check', 'rustfmt.toml', 'cargo.fmt')
+  }
+  return true
+}
+
+/** Go: test + vet are the two checks a go module always supports. */
+function detectGo(root: string, add: AddCommand): boolean {
+  if (!existsFile(root, 'go.mod')) return false
+  add('go test ./...', 'go.mod', 'go.test')
+  add('go vet ./...', 'go.mod', 'go.vet')
+  return true
+}
+
+/** Make: the generic fallback, only when no ecosystem-specific command exists. */
+function detectMake(root: string, add: AddCommand): boolean {
+  const makefile = ['Makefile', 'makefile', 'GNUmakefile'].find((name) => existsFile(root, name))
+  if (!makefile) return false
+  const text = readText(join(root, makefile)) ?? ''
+  const targets = new Set<string>()
+  for (const line of text.split(/\r?\n/)) {
+    // `target:`, but NOT a `VAR := value` / `VAR = value` assignment. The
+    // lookahead has to skip the optional space before `=` (`test := nope`).
+    const match = /^([A-Za-z0-9_.-]+)\s*:(?!=|\s*=)/.exec(line)
+    if (match) targets.add(match[1] as string)
+  }
+  if (targets.has('test')) add('make test', makefile, 'target.test')
+  if (targets.has('check')) add('make check', makefile, 'target.check')
+  return true
+}
+
+/**
+ * Inspect `projectRoot` and return a curated, ordered validation-command set.
+ *
+ * Never throws: unreadable or malformed manifests simply contribute nothing.
+ * The returned `commands` and `sources` always have the same length.
+ */
+export function detectValidationCommands(projectRoot: string): ValidationDetection {
+  const commands: string[] = []
+  const sources: DetectionSource[] = []
+  const seen = new Set<string>()
+  const add: AddCommand = (command, file, reason) => {
+    if (commands.length >= MAX_COMMANDS) return
+    if (seen.has(command)) return
+    seen.add(command)
+    commands.push(command)
+    sources.push({ file, reason })
+  }
+
+  let ecosystem: Ecosystem | null = null
+  const run = (name: Ecosystem, detect: (add: AddCommand) => boolean): void => {
+    const before = commands.length
+    let matched = false
+    try {
+      matched = detect(add)
+    } catch {
+      matched = false
+    }
+    if (matched && commands.length > before && ecosystem === null) ecosystem = name
+  }
+
+  run('node', (a) => detectNode(projectRoot, a))
+  run('python', (a) => detectPython(projectRoot, a))
+  run('rust', (a) => detectRust(projectRoot, a))
+  run('go', (a) => detectGo(projectRoot, a))
+  // Make is the generic wrapper: only consult it when nothing else produced a
+  // command, so a Makefile that just calls `npm test` does not double-report.
+  if (commands.length === 0) run('make', (a) => detectMake(projectRoot, a))
+
+  return { ecosystem, commands, sources }
+}
+
+/**
+ * Build the partial config update that installs a detected command set under
+ * the `default` module. The config tool deep-merges this into an existing
+ * `validation.commands` map, so other modules are preserved.
+ */
+export function buildValidationUpdates(commands: string[]): Record<string, unknown> {
+  return { validation: { commands: { default: [...commands] } } }
+}