iterate-plugin 2.3.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iterate-skill contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# iterate-plugin for DeepSeek Harness (dsh)
+
+`iterate-plugin` 是 [iterate](https://github.com/iterate-skill/iterate-skill) 技能的 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 插件，提供**自治闭环代码迭代**和**dry-run 纯多轮审查**能力。
+
+## 特性
+
+| 功能 | dry-run 模式 | normal 模式 |
+|------|-------------|------------|
+| 多轮收敛反复审查 | ✅ | ✅ |
+| 并行维度评审 | ✅ | ✅ |
+| 确定性聚合去重/排序 | ✅ | ✅ |
+| meta-review 报告一致性审计 | ✅ | ✅ |
+| 零文件修改（只读） | ✅ | ❌ |
+| 原子问题自动修复 | ❌ | ✅ |
+| 每轮修复后验证 | ❌ | ✅ |
+| 达标自停 | ✅ | ✅ |
+| 只修改 atomic 问题，保留 architectural 留待后续 | ❌ | ✅ |
+
+## 安装
+
+### 从 npm 安装（发布后）
+
+```bash
+dsh plugin --profile web add iterate-plugin
+# 或
+pnpm add iterate-plugin
+```
+
+### 本地开发 / 源码挂载
+
+```bash
+dsh plugin --profile web add /Volumes/Eng-Dev/iterate-skill/harness/iterate-plugin
+# 或
+pnpm add /path/to/iterate-skill/harness/iterate-plugin
+```
+
+然后在你的 profile `cordis.patch.yml` 添加：
+
+```yaml
+- insert:
+  - id: iterate-plugin
+    name: 'iterate-plugin'
+```
+
+## 使用
+
+### dry-run 模式（纯反复审查，不修改文件）
+
+当你想要 "只是反复审查，不修改文件"，prompt 示例：
+
+```
+dry-run review this project, find all issues across all dimensions
+```
+
+插件会自动触发 iterate 工作流：
+1. `plan` → 读取配置，生成评审计划
+2. `loop` → 每轮并行评审，只找新问题 → 确定性聚合去重 → 统计收敛 → 无新问题则停止
+3. `meta-review` → 审计报告一致性
+4. `report` → 输出最终结果
+
+### normal 模式（自治闭环迭代）
+
+当你想要 "iterate this project / fix the issues found"，prompt 示例：
+
+```
+iterate on this project, fix all atomic issues
+```
+
+工作流：
+1. `plan` → 读取配置
+2. `loop` → 并行评审 → 聚合去重 → 原子问题并行修复 → 执行验证命令 → 记录日志 → 无新问题则停止
+3. `report` → 输出修复统计
+
+## 项目配置
+
+在项目根目录放 `iterate.config.yaml`：
+
+```yaml
+# 评审目标（例如 "提高代码质量，修复潜在bug，改善可维护性"）
+goal: "Improve code quality of the project"
+# 评审维度（从本插件预定义维度选或自定义）
+dimensions:
+  - correctness
+  - security
+  - performance
+  - maintainability
+  - code-style
+# 最大评审轮次
+max_rounds: 3
+# 评审范围
+review:
+  scope: full  # full = 全项目，changed-only = 只看变更文件
+# 已知故意不修复的问题（评审会过滤掉，不再重复报告）
+personalization:
+  known_intentional:
+    - file: src/example.ts
+      line: 42
+      dimension: security
+      reason: "Intentional for demonstration"
+# 验证命令（修复后自动跑，结果记入日志）
+validation:
+  commands:
+    - npm test
+    - npm run typecheck
+```
+
+## 注册工具
+
+插件注册了 5 个工具：
+
+| 工具 | 功能 |
+|------|------|
+| `iterate_config` | 读取并验证 `iterate.config.yaml` |
+| `iterate_validate` | 运行白名单验证命令，返回结果 |
+| `iterate_decision_log` | 追加决策日志（只追加，不改旧） |
+| `iterate_context` | 读取 `SKILL.md` / `ITERATE.md` 上下文 |
+| `iterate_review` | 确定性评审引擎：`plan` 生成计划，`aggregate` 聚合结论，`meta-review` 审计报告 |
+
+## 设计
+
+插件遵循 dsh "everything-is-a-plugin" 架构：
+- 只做一件事：注入系统 prompt 教模型写 iterate workflow + 注册 5 个纯函数工具
+- 所有 orchestration 通过 dsh 原生 `workflow` + `agent` + `parallel` 完成
+- 核心逻辑（去重/过滤/排序/收敛/meta-audit）全部纯函数，可单元测试，无 I/O
+- 遵循 iterate 原技能的设计原则：确定性收敛，可审计，最小权限
+
+## 运行测试
+
+```bash
+cd harness/iterate-plugin
+npm install
+npm run typecheck
+npm test
+```
+
+所有测试通过：
+- 31 个单元测试全绿
+- 覆盖去重、过滤、排序、多轮收敛、meta-review 审计
+- 类型检查通过
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# iterate-plugin bundle layer — applied when a profile lists this bundle.
+# package.json declares `dsh.bundle.patch` pointing at this file.
+#
+# `name` is a PACKAGE NAME (resolved through the profile's node_modules or the
+# installation fallback $DSH_HOME/profiles/node_modules), NOT a relative path.
+# `iterate-plugin` is this package's main entry (→ src/index.ts).
+- insert:
+  - id: iterate-plugin
+    name: iterate-plugin

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "iterate-plugin",
+  "version": "2.3.6",
+  "description": "dsh plugin that turns the iterate skill into an autonomous closed-loop harness: plan -> parallel review xN -> atomic fixes -> validate -> loop -> auto-stop, plus a dry-run pure-review mode with multi-round convergence and a meta-review that audits the report and emits a final review report.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "iterate",
+    "code-review",
+    "autonomous",
+    "dry-run",
+    "cordis"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:script": "tsx --test test/script.test.ts",
+    "test:runtime": "tsx --test test/runtime.test.ts",
+    "test:loader": "tsx --test test/loader.test.ts",
+    "test:decisions": "tsx --test test/decisions.test.ts",
+    "test:validate": "tsx --test test/validate.test.ts"
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-workflow": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "js-yaml": "4.3.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "4.0.9",
+    "@types/node": "22.15.0",
+    "tsx": "4.20.3",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/config-loader.ts

@@ -0,0 +1,162 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import yaml from 'js-yaml'
+import type { IterateConfig } from './types.ts'
+
+/**
+ * Load and parse iterate.config.yaml from the project root.
+ * Returns null if the file is missing or invalid.
+ */
+export function loadConfig(projectRoot: string): IterateConfig | null {
+  try {
+    const content = readFileSync(join(projectRoot, 'iterate.config.yaml'), 'utf-8')
+    const parsed = yaml.load(content) as Record<string, unknown>
+    if (!parsed || typeof parsed !== 'object') return null
+    return parsed as unknown as IterateConfig
+  } 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(): IterateConfig {
+  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: Record<string, unknown>,
+  override: Record<string, unknown> | undefined,
+): Record<string, unknown> {
+  if (!override || typeof override !== 'object') return { ...base }
+  const out: Record<string, unknown> = { ...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 as Record<string, unknown>,
+        value as Record<string, unknown>,
+      )
+    } 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: string): {
+  config: IterateConfig
+  source: 'defaults' | 'override'
+  override: IterateConfig | null
+} {
+  const override = loadConfig(projectRoot)
+  if (!override) {
+    return { config: defaultConfig(), source: 'defaults', override: null }
+  }
+  const merged = mergeConfig(
+    defaultConfig() as unknown as Record<string, unknown>,
+    override as unknown as Record<string, unknown>,
+  ) as unknown as IterateConfig
+  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: string, predefinedCommands: string[]): boolean {
+  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: Record<string, string[]> | undefined,
+): string[] {
+  if (!commands || typeof commands !== 'object') return []
+  const out: string[] = []
+  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: unknown): string[] {
+  const errors: string[] = []
+  if (!config || typeof config !== 'object') {
+    errors.push('root')
+    return errors
+  }
+  const c = config as Record<string, unknown>
+  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 as Record<string, unknown>
+    if (!Array.isArray(v.command_whitelist)) errors.push('validation.command_whitelist')
+    if (!v.commands || typeof v.commands !== 'object') errors.push('validation.commands')
+  }
+  return errors
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * iterate-plugin — dsh plugin for the iterate autonomous closed-loop workflow
+ *
+ * Architecture:
+ * - The plugin registers 4 tools (config, validate, decision-log, context)
+ * - 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 4 tools to do real work (read config, run validation, log decisions)
+ *
+ * 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/        — 4 tool implementations
+ * - src/config-loader.ts — YAML config loading
+ * - src/types.ts     — Shared types
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { registerConfigTool } from './tools/config.ts'
+import { registerValidateTool } from './tools/validate.ts'
+import { registerDecisionLogTool } from './tools/decision-log.ts'
+import { registerContextTool } from './tools/context.ts'
+import { registerReviewTool } from './tools/review.ts'
+import { ITERATE_SKILL_PROMPT } from './skill-prompt.ts'
+
+export const name = 'iterate-plugin'
+export const inject = ['tools', 'systemPrompt']
+
+export function apply(ctx: Context): void {
+  // 1. Register the 5 core tools
+  registerConfigTool(ctx)
+  registerValidateTool(ctx)
+  registerDecisionLogTool(ctx)
+  registerContextTool(ctx)
+  registerReviewTool(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,
+  })
+}