iterate-plugin 2.5.0 → 2.7.0

package/README.md

@@ -2,10 +2,12 @@
 
 > **开发与评审在 [iterate-skill 主仓库](https://github.com/jingzhao-l/iterate-skill) 完成**：插件代码由主仓库统一维护，通过 `git subtree` 同步到本仓库；**版本发版与 npm 发布在本仓库（插件仓库）进行**，作为 dsh 生态的正式发布位。欢迎 **star / fork 主仓库** 并在 [主仓库 Issues](https://github.com/jingzhao-l/iterate-skill/issues) 反馈问题。
 
-`iterate-plugin` 是 [iterate](https://github.com/iterate-skill/iterate-skill) 技能的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件，提供**自治闭环代码迭代**和**dry-run 纯多轮审查**能力。
+`iterate-plugin` 是 [iterate](https://github.com/jingzhao-l/iterate-skill) 技能的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件，提供**自治闭环代码迭代**和 **dry-run 纯多轮审查**能力。除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。
 
 ## 特性
 
+### 两种运行模式
+
 | 功能 | dry-run 模式 | normal 模式 |
 |------|-------------|------------|
 | 多轮收敛反复审查 | ✅ | ✅ |
@@ -15,12 +17,37 @@
 | 零文件修改（只读） | ✅ | ❌ |
 | 原子问题自动修复 | ❌ | ✅ |
 | 每轮修复后验证 | ❌ | ✅ |
+| 修复失败回滚 | ❌ | ✅ |
 | 达标自停 | ✅ | ✅ |
 | 只修改 atomic 问题，保留 architectural 留待后续 | ❌ | ✅ |
+| 断点保存 / 恢复（长迭代续跑） | ✅ | ✅ |
+
+### 工具层
+
+- **13 个注册工具**：`iterate_config` / `iterate_validate` / `iterate_decision_log` / `iterate_context` / `iterate_review` / `iterate_triage` / `iterate_fix` / `iterate_diff` / `iterate_rollback` / `iterate_checkpoint` / `iterate_status` / `iterate_history` / `iterate_prune`
+- **findings 分诊闭环**：审查 → UI 分诊（y/n/a）→ `iterate_triage` 写回 `known_intentional` → 下一轮自动过滤
+- **结构化修复系统**：每次修复先备份、写注册表、记录 diff，验证失败可 `iterate_rollback` 还原
+- **断点续跑**：长迭代在每轮开头保存 checkpoint，中断后可恢复进度
+- **历史审计**：`iterate_history` 读取决策日志（按类型/时间/数量过滤）与修复注册表汇总，审查运行过程与修复明细
+- **运行时清理**：`iterate_prune` 清理过期的决策日志条目、陈旧断点、孤儿修复备份与空轮次；默认 dry-run 只报告不删除，显式 `dryRun:false` 才真正清理，每次清理写入决策日志
+- **配置读写**：`iterate_config` 支持带校验、备份、回滚的局部写入
+
+### UI 层（客户端免构建槽位）
+
+| UI 组件 | 挂载槽位 | 功能 |
+|---------|---------|------|
+| 收敛看板 `ConvergenceDashboard` | `conversation.input.dock` | 输入框上方实时显示轮次进度条、严重度统计、维度徽章、趋势迷你图，normal 模式另显示修复计数徽章 |
+| Findings 分诊面板 `TriagePanel` | `conversation.chat.turnTail` | 逐条 y/n/a 判定，支持筛选、批量（含一键全选所有 findings）、键盘快捷键、localStorage 持久化、复制 YAML/应用指令 |
+| 收敛统计卡片 `StatsCard` | `conversation.chat.turnTail` | 无 findings 时显示收敛统计、历史轮次表、趋势图、完成摘要 |
+| iterate 主题皮肤 | `theme.overrideTokens` | 暖琥珀配色的 13 个 dsw token 覆盖，明暗双模式，可在设置页开关 |
+| 进度胶囊 `ProgressCapsule` | `shell.overlay` | 每轮完成/收敛时右下角弹出通知（含收敛确认） |
+| iterate 设置区 `SettingsPanel` | `settings.section` | 主题开关、分诊持久化说明、配置管理指引、运行时状态概览（产物布局 + 查看/清理工具指引）、一键清空分诊数据 |
+
+UI 层为**防御式设计**：`slots` / `theme` / `React` 任一不可用时自动降级，不会崩溃客户端。
 
 ## 安装
 
-### 从 npm 安装（发布后）
+### 从 npm 安装
 
 ```bash
 dsh plugin --profile web add iterate-plugin
@@ -28,10 +55,20 @@ dsh plugin --profile web add iterate-plugin
 pnpm add iterate-plugin
 ```
 
+### 从 GitHub 安装（dsh 生态第三方安装方式）
+
+dsh 官方支持从 GitHub 插件仓库直接安装：`dsh plugin --profile web add "github:owner/repo#ref"`（仓库根即插件，声明 `dsh.bundle` 后自动启用）。本插件在 [iterate-plugin 独立仓库](https://github.com/jingzhao-l/iterate-plugin) 维护仓库根即插件的发布位，由主仓库通过 `git subtree` 同步，内容与 npm 包一致：
+
+```bash
+dsh plugin --profile web add "github:jingzhao-l/iterate-plugin#main"
+```
+
+安装完成后需重启 dsh 服务（建议 `dsh web --patch`）并刷新页面，宿主与客户端 UI 层才会加载。
+
 ### 本地开发 / 源码挂载
 
 ```bash
-dsh plugin --profile web add /Volumes/Eng-Dev/iterate-skill/harness/iterate-plugin
+dsh plugin --profile web add /path/to/iterate-skill/harness/iterate-plugin
 # 或
 pnpm add /path/to/iterate-skill/harness/iterate-plugin
 ```
@@ -44,6 +81,8 @@ pnpm add /path/to/iterate-skill/harness/iterate-plugin
     name: 'iterate-plugin'
 ```
 
+> 插件包自带 `dsh.bundle.patch`（即 `cordis.patch.yml`），npm 包内 `files` 已白名单化（`src` / `lib` / `cordis.patch.yml` / `README.md` / `LICENSE`）。
+
 ## 使用
 
 ### dry-run 模式（纯反复审查，不修改文件）
@@ -55,6 +94,7 @@ dry-run review this project, find all issues across all dimensions
 ```
 
 插件会自动触发 iterate 工作流：
+
 1. `plan` → 读取配置，生成评审计划
 2. `loop` → 每轮并行评审，只找新问题 → 确定性聚合去重 → 统计收敛 → 无新问题则停止
 3. `meta-review` → 审计报告一致性
@@ -69,8 +109,9 @@ iterate on this project, fix all atomic issues
 ```
 
 工作流：
+
 1. `plan` → 读取配置
-2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 记录日志 → 无新问题则停止
+2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 验证失败则回滚 → 记录日志 → 无新问题则停止
 3. `report` → 输出修复统计
 
 ## 项目配置
@@ -92,6 +133,9 @@ max_rounds: 3
 # 评审范围
 review:
   scope: full  # full = 全项目，changed-only = 只看变更文件
+# 原子修复阈值（单次修复允许改动的最大行数，超过需 force）
+atomic:
+  max_lines: 20
 # 已知故意不修复的问题（评审会过滤掉，不再重复报告）
 personalization:
   known_intentional:
@@ -106,24 +150,48 @@ validation:
     - npm run typecheck
 ```
 
-## 注册工具
+> 配置可通过 `iterate_config` 工具读取与**校验式局部写入**（自动备份，写入失败自动回滚）。
 
-插件注册了 5 个工具：
+## 注册工具（13 个）
 
 | 工具 | 功能 |
 |------|------|
-| `iterate_config` | 读取并验证 `iterate.config.yaml` |
+| `iterate_config` | 读取 / 写入 `iterate.config.yaml`。`operation=read` 返回完整配置或指定 section；`operation=write` 做 schema 校验、备份后局部合并写入，失败自动回滚 |
 | `iterate_validate` | 运行白名单验证命令，返回结果 |
-| `iterate_decision_log` | 追加决策日志（只追加，不改旧） |
+| `iterate_decision_log` | 追加决策日志（只追加，不改旧），存储于 `.iterate/decision-log.jsonl` |
 | `iterate_context` | 读取 `SKILL.md` / `ITERATE.md` 上下文 |
-| `iterate_review` | 确定性评审引擎：`plan` 生成计划，`aggregate` 聚合结论，`meta-review` 审计报告 |
+| `iterate_review` | 确定性评审引擎：`plan` 生成计划，`aggregate` 聚合去重 + 收敛统计，`meta-review` 审计报告一致性。纯计算，不触碰文件系统 |
+| `iterate_triage` | 管理 `personalization.known_intentional`：`apply` 校验、去重（file\|dimension\|line）、备份后写回配置；`list` 读回当前条目。是浏览器分诊面板写回配置的唯一通道 |
+| `iterate_fix` | 应用**一个原子修复**：校验相对路径、备份原文件、按 `atomic.max_lines` 强制原子性（可 `force` 跳过）、写入新内容、记录 FixRecord 与 `atomic_fix` 日志。normal 模式唯一合法的改文件入口 |
+| `iterate_diff` | 查看修复累积变更：指定 `file` 返回相对首个备份的 unified diff；省略则返回每个已修复文件的汇总 |
+| `iterate_rollback` | 回滚一个已应用的修复：从备份还原文件、从注册表移除该 FixRecord、追加 `revert` 日志。用于某轮验证失败后 |
+| `iterate_checkpoint` | 迭代断点：`save` 保存当前进度到 `.iterate/checkpoint.json`，`load` 读回，`clear` 清除。长迭代可中断续跑 |
+| `iterate_status` | 汇总当前迭代状态：模式、当前轮/总轮、已修复数、剩余 architectural、决策日志条数、是否存在 checkpoint |
+| `iterate_history` | 读取迭代历史（只读）：决策日志条目（可按 `type` / `since` / `limit` 过滤，默认取最新 50 条，上限 200 条）+ 修复注册表汇总（各轮 fixed/failed 计数）。用于审查运行过程、审计日志、盘点修复 |
+| `iterate_prune` | 清理运行时产物：过期决策日志条目（按 `retainDays`，默认 30 天）、陈旧断点、孤儿修复备份、空轮次。默认 dry-run 只报告不删除；`dryRun:false` 才真正清理，每次清理写入决策日志 |
+
+## 运行时产物布局
+
+所有运行时状态都落在项目根目录的 `.iterate/` 下（可由 `.gitignore` 排除）：
+
+```
+.iterate/
+  decision-log.jsonl      # 追加式决策日志（plan/review/fix/revert…）
+  checkpoint.json         # 迭代断点（断点续跑）
+  fixes/
+    registry.json         # 修复注册表（FixRecord 列表，按轮次组织）
+    <fix-id>_<ts>.bak     # 每次修复前的原文件备份
+```
 
 ## 设计
 
 插件遵循 dsh "everything-is-a-plugin" 架构：
-- 只做一件事：注入系统 prompt 教模型写 iterate workflow + 注册 5 个纯函数工具
-- 所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成
-- 核心逻辑（去重/过滤/排序/收敛/meta-audit）全部纯函数，可单元测试，无 I/O
+
+- **只做两件事**：注入系统 prompt 教模型写 iterate workflow + 注册 13 个纯函数工具
+- **所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成**
+- **核心逻辑全部纯函数**（去重/过滤/排序/收敛/meta-audit/diff 计算/历史过滤/清理报告），可单元测试，无 I/O
+- **安全模型**：文件写入限定在解析后的项目根目录内（路径遍历防护）；写文件前必备份，失败回滚；配置写入同样备份 + 回滚；`iterate_prune` 默认 dry-run、只清理 `.iterate/` 下产物、每次清理写日志；`iterate_fix` 对 content 设字符上限、`iterate_triage` 对 entries 设数量上限，防止异常超大负载
+- **UI 免构建**：`lib/client.js` 用 `React.createElement` 树 + 注入 `<style>` 标签，全部颜色走 `--dsw-*` 令牌，缺服务自动降级
 - 遵循 iterate 原技能的设计原则：确定性收敛，可审计，最小权限
 
 ## 运行测试
@@ -136,9 +204,9 @@ npm test
 ```
 
 所有测试通过：
-- 63 个单元测试全绿
-- 覆盖去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制
-- 类型检查通过
+
+- **212 个单元测试全绿**，类型检查通过
+- 覆盖：去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制、配置读写与回滚、triage 合并、diff 计算、checkpoint 校验、修复注册表、历史读取与过滤、prune 清理报告与 dry-run 语义、UI 纯函数（select-all 键、运行时状态指引）等
 
 ## License
 

package/dist/config-loader.js

@@ -0,0 +1,171 @@
+import { readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import yaml from 'js-yaml';
+/**
+ * Load and parse iterate.config.yaml from the project root.
+ * Returns null if the file is missing or invalid.
+ */
+export function loadConfig(projectRoot) {
+    try {
+        const content = readFileSync(join(projectRoot, 'iterate.config.yaml'), 'utf-8');
+        const parsed = yaml.load(content);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Sensible defaults for every config field. These are the "Master" config:
+ * when a project has no iterate.config.yaml (or only partial overrides), every
+ * missing key is filled from here so the plugin is usable out of the box while
+ * never inventing trusted validation commands (they must be configured).
+ */
+export function defaultConfig() {
+    return {
+        goal: 'Improve code quality and maintainability',
+        max_rounds: 7,
+        language: 'en',
+        dimensions: [
+            'correctness',
+            'security',
+            'performance',
+            'architecture',
+            'style-tests',
+            'tech-debt',
+            'spec-compliance',
+            'frontend-backend',
+            'ui-ux',
+        ],
+        review: { scope: 'full' },
+        atomic: { max_lines: 20, max_adjacent_methods: 3 },
+        git: {
+            target_branch: 'main',
+            use_worktree: false,
+            push_per_round: false,
+            auto_merge: false,
+        },
+        validation: { command_whitelist: [], commands: {} },
+        reviewer: { output_schema_validation: true },
+    };
+}
+/**
+ * Recursively merge `override` on top of `base`.
+ * - Missing keys in `base` are added from `override`.
+ * - Present keys in `override` win.
+ * - Plain objects are merged recursively; arrays and scalars are replaced
+ *   wholesale by the override (arrays are NOT concatenated).
+ * Returns a NEW object; neither input is mutated.
+ */
+export function mergeConfig(base, override) {
+    if (!override || typeof override !== 'object')
+        return { ...base };
+    const out = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (value === undefined)
+            continue;
+        const baseValue = out[key];
+        if (baseValue &&
+            typeof baseValue === 'object' &&
+            !Array.isArray(baseValue) &&
+            value &&
+            typeof value === 'object' &&
+            !Array.isArray(value)) {
+            out[key] = mergeConfig(baseValue, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Load the EFFECTIVE config for a project: project-root overrides merged on top
+ * of the built-in defaults ("Master + Overrides"). Never returns null — a
+ * project without a config file simply runs on the defaults (with an empty
+ * validation command set, so nothing untrusted can ever execute).
+ */
+export function loadEffectiveConfig(projectRoot) {
+    const override = loadConfig(projectRoot);
+    if (!override) {
+        return { config: defaultConfig(), source: 'defaults', override: null };
+    }
+    const merged = mergeConfig(defaultConfig(), override);
+    return { config: merged, source: 'override', override };
+}
+/**
+ * Check whether a command is in the predefined commands list.
+ * A command is allowed if it is EXACTLY (after trim) listed in any
+ * module's command array in `validation.commands`.
+ * This replaces the old prefix-based whitelist at runtime — the
+ * `command_whitelist` is still used for config-time validation only.
+ */
+export function isCommandAllowed(command, predefinedCommands) {
+    const trimmed = command.trim();
+    return predefinedCommands.includes(trimmed);
+}
+/**
+ * Flatten all commands from `validation.commands` into a single string array.
+ * Used for runtime exact-match checking.
+ */
+export function flattenCommands(commands) {
+    if (!commands || typeof commands !== 'object')
+        return [];
+    const out = [];
+    for (const v of Object.values(commands)) {
+        if (Array.isArray(v))
+            out.push(...v);
+    }
+    return out;
+}
+/**
+ * Validate that the config has all required fields.
+ * Returns an array of missing field paths.
+ */
+export function validateConfig(config) {
+    const errors = [];
+    if (!config || typeof config !== 'object') {
+        errors.push('root');
+        return errors;
+    }
+    const c = config;
+    if (!c.goal)
+        errors.push('goal');
+    if (!Array.isArray(c.dimensions))
+        errors.push('dimensions');
+    if (!c.validation || typeof c.validation !== 'object') {
+        errors.push('validation');
+    }
+    else {
+        const v = c.validation;
+        if (!Array.isArray(v.command_whitelist))
+            errors.push('validation.command_whitelist');
+        if (!v.commands || typeof v.commands !== 'object')
+            errors.push('validation.commands');
+    }
+    return errors;
+}
+/**
+ * Resolve a caller-supplied project root to a safe absolute path.
+ *
+ * Every tool accepts a model-controlled `path` argument. Before it is used in
+ * any file read/write or as a command `cwd`, it must be sanitized:
+ *  - an empty/missing `path` falls back to the current working directory;
+ *  - the path is resolved to an absolute path (collapsing `..` and symlinks);
+ *  - the filesystem root (`/`) is refused — it would let a prompt point tools
+ *    at arbitrary system directories (path-traversal escape).
+ *
+ * Returns `{ ok: true, root }` on success, or `{ ok: false, reason }` when the
+ * path is unsafe; callers must short-circuit on the failure and return a
+ * structured error instead of proceeding.
+ */
+export function resolveProjectRoot(input) {
+    const raw = (input ?? '').trim();
+    const root = raw ? resolve(raw) : resolve(process.cwd());
+    if (!root || root === sep) {
+        return { ok: false, reason: 'Refusing filesystem root as project root.' };
+    }
+    return { ok: true, root };
+}

package/dist/config-write.js

@@ -0,0 +1,174 @@
+/**
+ * src/config-write.ts — shared helpers for safely WRITING iterate.config.yaml.
+ *
+ * Used by the `iterate_config` write operation. Provides:
+ *   - validateConfigUpdates : validate a caller-supplied partial update
+ *   - applyConfigUpdates    : merge a partial update into the current config
+ *   - writeConfigFile       : backup + write + rollback on failure
+ *
+ * The security posture mirrors the triage tool: never overwrite a malformed
+ * config, always back up before writing, roll back on failure.
+ */
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+/** Config file name (must match config-loader). */
+export const CONFIG_FILE = 'iterate.config.yaml';
+/** Backup suffix helper (filesystem-safe timestamp). */
+export function configBackupSuffix(now = new Date()) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * Validate a partial config update.
+ * Returns an array of error strings (empty when the update is valid).
+ */
+export function validateConfigUpdates(updates) {
+    const errors = [];
+    if (!updates || typeof updates !== 'object' || Array.isArray(updates)) {
+        return ['updates must be a JSON object'];
+    }
+    if ('goal' in updates && typeof updates.goal !== 'string') {
+        errors.push('updates.goal must be a string');
+    }
+    if ('language' in updates && updates.language !== 'zh' && updates.language !== 'en') {
+        errors.push('updates.language must be "zh" or "en"');
+    }
+    if ('dimensions' in updates) {
+        if (!Array.isArray(updates.dimensions) || updates.dimensions.some((d) => typeof d !== 'string' || d.trim().length === 0)) {
+            errors.push('updates.dimensions must be an array of non-empty strings');
+        }
+    }
+    if ('max_rounds' in updates) {
+        if (typeof updates.max_rounds !== 'number' || !Number.isInteger(updates.max_rounds) || updates.max_rounds < 1) {
+            errors.push('updates.max_rounds must be a positive integer');
+        }
+    }
+    if ('review' in updates) {
+        const r = updates.review;
+        if (!r || typeof r !== 'object') {
+            errors.push('updates.review must be an object');
+        }
+        else if (r.scope !== undefined && r.scope !== 'full' && r.scope !== 'changed-only') {
+            errors.push('updates.review.scope must be "full" or "changed-only"');
+        }
+    }
+    if ('atomic' in updates) {
+        const a = updates.atomic;
+        if (!a || typeof a !== 'object') {
+            errors.push('updates.atomic must be an object');
+        }
+        else {
+            if (a.max_lines !== undefined && (typeof a.max_lines !== 'number' || !Number.isInteger(a.max_lines) || a.max_lines < 1)) {
+                errors.push('updates.atomic.max_lines must be a positive integer');
+            }
+            if (a.max_adjacent_methods !== undefined && (typeof a.max_adjacent_methods !== 'number' || a.max_adjacent_methods < 0)) {
+                errors.push('updates.atomic.max_adjacent_methods must be a non-negative number');
+            }
+        }
+    }
+    if ('git' in updates) {
+        const g = updates.git;
+        if (!g || typeof g !== 'object') {
+            errors.push('updates.git must be an object');
+        }
+        else {
+            if (g.target_branch !== undefined && typeof g.target_branch !== 'string') {
+                errors.push('updates.git.target_branch must be a string');
+            }
+            for (const boolKey of ['use_worktree', 'push_per_round', 'auto_merge']) {
+                if (g[boolKey] !== undefined && typeof g[boolKey] !== 'boolean') {
+                    errors.push(`updates.git.${boolKey} must be a boolean`);
+                }
+            }
+        }
+    }
+    if ('validation' in updates) {
+        const v = updates.validation;
+        if (!v || typeof v !== 'object') {
+            errors.push('updates.validation must be an object');
+        }
+        else if ('commands' in v && v.commands !== undefined && typeof v.commands !== 'object') {
+            errors.push('updates.validation.commands must be an object of command arrays');
+        }
+    }
+    if ('personalization' in updates && (!updates.personalization || typeof updates.personalization !== 'object')) {
+        errors.push('updates.personalization must be an object');
+    }
+    if ('onboarding' in updates && (!updates.onboarding || typeof updates.onboarding !== 'object')) {
+        errors.push('updates.onboarding must be an object');
+    }
+    return errors;
+}
+/** Recursively merge `updates` over `base` (arrays replaced wholesale). */
+export function applyConfigUpdates(base, updates) {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(updates)) {
+        if (value === undefined)
+            continue;
+        const baseValue = out[key];
+        if (baseValue &&
+            typeof baseValue === 'object' &&
+            !Array.isArray(baseValue) &&
+            value &&
+            typeof value === 'object' &&
+            !Array.isArray(value)) {
+            out[key] = applyConfigUpdates(baseValue, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Read the raw config object from disk (empty object when missing).
+ * Throws when the file exists but cannot be parsed as a YAML mapping
+ * (never overwrite a malformed config).
+ */
+export function readRawConfig(configPath) {
+    if (!existsSync(configPath))
+        return {};
+    const content = readFileSync(configPath, 'utf-8');
+    let parsed;
+    try {
+        parsed = yaml.load(content);
+    }
+    catch {
+        throw new Error('existing iterate.config.yaml is not a valid YAML mapping');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('existing iterate.config.yaml is not a valid YAML mapping');
+    }
+    return parsed;
+}
+/**
+ * Write a config object to disk with backup + rollback.
+ * Returns `{ ok: true, backupPath }` or `{ ok: false, error }`.
+ */
+export function writeConfigFile(projectRoot, config) {
+    const configPath = join(projectRoot, CONFIG_FILE);
+    const hadFile = existsSync(configPath);
+    const backupPath = hadFile ? `${configPath}.bak-${configBackupSuffix()}` : null;
+    if (backupPath) {
+        try {
+            copyFileSync(configPath, backupPath);
+        }
+        catch (err) {
+            return { ok: false, error: `failed to create backup: ${String(err)}` };
+        }
+    }
+    try {
+        writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8');
+    }
+    catch (err) {
+        try {
+            if (backupPath)
+                copyFileSync(backupPath, configPath);
+        }
+        catch {
+            // Rollback failure is reported, never swallowed silently.
+        }
+        return { ok: false, error: `failed to write config: ${String(err)}` };
+    }
+    return { ok: true, backupPath };
+}

package/dist/index.js

@@ -0,0 +1,58 @@
+/**
+ * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
+ *
+ * Architecture:
+ * - The plugin registers 6 tools (config, validate, decision-log, context, review, triage)
+ * - The plugin injects a system prompt section teaching the iterate workflow pattern
+ * - The model (prompted by the skill) writes a workflow script using dsh's `workflow` tool
+ * - The workflow script uses `agent()` / `parallel()` / `phase()` / `log()` to orchestrate
+ * - Subagents use the 6 tools to do real work (read config, run validation, log decisions, review, triage)
+ *
+ * Tool invocation model:
+ * - Workflow script CANNOT call tools directly (sandboxed vm, no Node API)
+ * - Workflow script spawns subagents via `agent(prompt, opts)`
+ * - Subagents are full agent sessions with access to all registered tools
+ * - The script is pure orchestration: fan-out, aggregate, loop, stop
+ *
+ * Key files:
+ * - src/index.ts      — Plugin entry: register tools + inject skill prompt
+ * - src/tools/        — 6 tool implementations + meta-review/review engines
+ * - src/config-loader.ts — YAML config loading
+ * - src/types.ts     — Shared types
+ */
+import { registerConfigTool } from "./tools/config.js";
+import { registerValidateTool } from "./tools/validate.js";
+import { registerDecisionLogTool } from "./tools/decision-log.js";
+import { registerContextTool } from "./tools/context.js";
+import { registerReviewTool } from "./tools/review.js";
+import { registerTriageTool } from "./tools/triage.js";
+import { registerFixTool, registerDiffTool, registerRollbackTool } from "./tools/fix.js";
+import { registerCheckpointTool, registerStatusTool } from "./tools/checkpoint.js";
+import { registerHistoryTool } from "./tools/history.js";
+import { registerPruneTool } from "./tools/prune.js";
+import { ITERATE_SKILL_PROMPT } from "./skill-prompt.js";
+export const name = 'iterate-plugin';
+export const inject = ['tools', 'systemPrompt'];
+export function apply(ctx) {
+    // 1. Register the 11 tools
+    registerConfigTool(ctx);
+    registerValidateTool(ctx);
+    registerDecisionLogTool(ctx);
+    registerContextTool(ctx);
+    registerReviewTool(ctx);
+    registerTriageTool(ctx);
+    registerFixTool(ctx);
+    registerDiffTool(ctx);
+    registerRollbackTool(ctx);
+    registerCheckpointTool(ctx);
+    registerStatusTool(ctx);
+    registerHistoryTool(ctx);
+    registerPruneTool(ctx);
+    // 2. Inject the iterate skill prompt as a system prompt section
+    // This teaches the model how to write iterate workflow scripts using the tools.
+    ctx.systemPrompt.section({
+        name: 'iterate-skill',
+        order: 100,
+        text: ITERATE_SKILL_PROMPT,
+    });
+}