iterate-plugin 2.3.6 → 2.3.7

package/README.md

@@ -1,5 +1,7 @@
 # iterate-plugin for DeepSeek Harness (dsh)
 
+> **开发与评审在 [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 纯多轮审查**能力。
 
 ## 特性
@@ -134,8 +136,8 @@ npm test
 ```
 
 所有测试通过：
-- 31 个单元测试全绿
-- 覆盖去重、过滤、排序、多轮收敛、meta-review 审计
+- 63 个单元测试全绿
+- 覆盖去重、过滤、排序、多轮收敛、meta-review 审计、路径安全、超时钳制
 - 类型检查通过
 
 ## License

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "iterate-plugin",
-  "version": "2.3.6",
+  "version": "2.3.7",
   "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",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jingzhao-l/iterate-skill.git",
+    "directory": "harness/iterate-plugin"
+  },
+  "homepage": "https://github.com/jingzhao-l/iterate-skill#readme",
+  "bugs": {
+    "url": "https://github.com/jingzhao-l/iterate-skill/issues"
+  },
   "keywords": [
     "dsh-plugin",
     "deepseek-harness",
@@ -34,10 +43,6 @@
   "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": {

package/src/config-loader.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, resolve, sep } from 'node:path'
 import yaml from 'js-yaml'
 import type { IterateConfig } from './types.ts'
 
@@ -159,4 +159,30 @@ export function validateConfig(config: unknown): string[] {
     if (!v.commands || typeof v.commands !== 'object') errors.push('validation.commands')
   }
   return errors
+}
+
+/** Result of resolving/validating a caller-supplied project root. */
+export type ProjectRootResult = { ok: true; root: string } | { ok: false; reason: string }
+
+/**
+ * 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?: string): ProjectRootResult {
+  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/src/review.ts

@@ -36,7 +36,12 @@ export const SEVERITY_RANK: Record<ReviewFinding['severity'], number> = {
 /** Sort findings by severity (most severe first), then by file path. */
 export function sortFindings(findings: ReviewFinding[]): ReviewFinding[] {
   return [...findings].sort((a, b) => {
-    const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]
+    // Guard against an out-of-spec severity string (e.g. from a model that
+    // bypassed the schema): treat it as the least severe so NaN never enters
+    // the comparator and ordering stays deterministic.
+    const rankA = SEVERITY_RANK[a.severity] ?? SEVERITY_RANK.low
+    const rankB = SEVERITY_RANK[b.severity] ?? SEVERITY_RANK.low
+    const bySeverity = rankA - rankB
     if (bySeverity !== 0) return bySeverity
     const byFile = a.file.localeCompare(b.file)
     if (byFile !== 0) return byFile
@@ -288,6 +293,8 @@ export function reviewerTaskPrompt(input: {
   mode: 'normal' | 'dry-run'
   alreadyKnown?: ReviewFinding[]
   outputLanguage: string
+  /** Atomic fix threshold from config.atomic. */
+  maxLines: number
 }): string {
   const parts: string[] = []
   parts.push(
@@ -313,7 +320,7 @@ export function reviewerTaskPrompt(input: {
     `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
       'line (optional integer), severity (critical/high/medium/low), summary (one line), ' +
       'failure_scenario (how/when it fails, specific evidence), suggested_fix (the concrete fix), ' +
-      'is_atomic (true if the fix is <= {atomic.max_lines} lines within a SINGLE file/function, else false).',
+      `is_atomic (true if the fix is <= ${input.maxLines} lines within a SINGLE file/function, else false).`,
     `Write summaries and details in ${input.outputLanguage}.`,
   )
   return parts.join('\n')
@@ -351,6 +358,7 @@ export function buildReviewPlan(input: {
         mode: input.mode,
         alreadyKnown: [],
         outputLanguage: language,
+        maxLines: input.config.atomic.max_lines,
       }),
       findingsSchema: findingsSchema(),
     })),

package/src/skill-prompt.ts

@@ -47,7 +47,8 @@ const plan = (planRes && planRes.plan) ? planRes.plan : null
 if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
 const dims = plan.dimensions.map(d => d.id)
 const maxRounds = plan.maxReviewRounds
-const known = []            // cumulative deduped findings across rounds
+const knownIntentional = (plan.knownIntentional || [])   // config personalization filter, applied in aggregate
+let known = []              // cumulative DEDUPED findings fed back to reviewers
 const rounds = []           // raw per-round findings
 
 phase('review')
@@ -60,13 +61,15 @@ for (let r = 1; r <= maxRounds; r++) {
   )))
   const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
   rounds.push(thisRound)
-  known.push(...thisRound.findings)   // rough accumulation; final dedupe is deterministic in aggregate
-  // Check convergence deterministically
+  // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
   const agg = await agent(
-    'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + '}) and return the report JSON.',
+    'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
     { label: 'review:aggregate:r' + r }
   )
-  if (agg && agg.report && agg.report.convergence.findingsByRound[r-1] === 0) {
+  // Feed the DEDUPED + already-filtered set back (not raw findings) so the known
+  // list stays bounded and reviewers never see the same issue twice.
+  if (agg && agg.report && Array.isArray(agg.report.findings)) known = agg.report.findings
+  if (agg && agg.report && agg.report.convergence && agg.report.convergence.findingsByRound[r-1] === 0) {
     log('round ' + r + ' found 0 new findings — converged')
     break
   }
@@ -74,7 +77,7 @@ for (let r = 1; r <= maxRounds; r++) {
 
 phase('report')
 const finalAgg = await agent(
-  'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + '}) and return the report JSON.',
+  'Call iterate_review({operation:"aggregate", mode:"dry-run", rounds:' + JSON.stringify(rounds) + ', maxReviewRounds:' + maxRounds + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
   { label: 'review:aggregate:final' }
 )
 const report = (finalAgg && finalAgg.report) ? finalAgg.report : null
@@ -124,16 +127,19 @@ Canonical script — reproduce this structure exactly (adjust dims via the plan)
 \`\`\`js
 // args = { mode: "normal", maxRounds? }
 phase('plan')
-await agent(
+const configRes = await agent(
   'Call iterate_config({ validate: true }) and return the config JSON.',
   { label: 'config:read' }
 )
+const cfg = (configRes && configRes.config) ? configRes.config : null
+const atomicMaxLines = (cfg && cfg.atomic && cfg.atomic.max_lines) ? cfg.atomic.max_lines : 20
 const planRes = await agent(
   'Call iterate_review({operation:"plan", mode:"normal", maxReviewRounds:' + (args.maxRounds || 3) + '}) and return the plan JSON.',
   { label: 'review:plan' }
 )
 const plan = (planRes && planRes.plan) ? planRes.plan : null
 if (!plan || !Array.isArray(plan.dimensions)) throw new Error('plan failed: iterate_review did not return a valid plan')
+const knownIntentional = (plan.knownIntentional || [])   // config personalization filter, applied in aggregate
 const dims = plan.dimensions.map(d => d.id)
 const maxRounds = plan.maxReviewRounds
 const rounds = []          // findings per review round (each on the then-current code state)
@@ -154,7 +160,7 @@ for (let r = 1; r <= maxRounds; r++) {
 
   // Deterministic dedupe / known_intentional filter / severity sort for this round.
   const agg = await agent(
-    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + '}) and return the report JSON.',
+    'Call iterate_review({operation:"aggregate", mode:"normal", rounds:' + JSON.stringify([thisRound]) + ', knownIntentional:' + JSON.stringify(knownIntentional) + '}) and return the report JSON.',
     { label: 'review:aggregate:r' + r }
   )
   const findings = (agg && agg.report && agg.report.findings) ? agg.report.findings : thisRound.findings
@@ -162,14 +168,25 @@ for (let r = 1; r <= maxRounds; r++) {
   const remaining = findings.filter(f => f.is_atomic !== true)
 
   if (atomic.length > 0) {
-    await parallel(atomic.map(f => () => agent(
-      'Fix this finding with the smallest possible change (single file, single function, <=20 lines). ' +
-      JSON.stringify(f) + '. Verify the edit locally before finishing.',
-      { label: 'fix:' + f.file + ':' + (f.line || 0), phase: 'fix' }
+    // Group atomic fixes by file. All edits to the SAME file are applied by a
+    // single fixer agent (serial within a file), avoiding concurrent-write
+    // races; different files still run in parallel.
+    const byFile = {}
+    atomic.forEach(f => { (byFile[f.file] = byFile[f.file] || []).push(f) })
+    await parallel(Object.keys(byFile).map(file => () => agent(
+      'Apply ALL of these fixes to ' + file + ' in ONE pass with the smallest possible changes ' +
+      '(each <= ' + atomicMaxLines + ' lines, single function). ' + JSON.stringify(byFile[file]) + '. Verify the edit locally before finishing.',
+      { label: 'fix:' + file, phase: 'fix' }
     )))
     fixedCount += atomic.length
   }
-  architectural.push(...remaining)
+
+  // Cross-round dedupe of architectural findings before accumulating.
+  const seenKeys = architectural.map(a => a.file + '|' + a.dimension + '|' + a.summary)
+  for (const f of remaining) {
+    const key = f.file + '|' + f.dimension + '|' + f.summary
+    if (seenKeys.indexOf(key) < 0) { architectural.push(f); seenKeys.push(key) }
+  }
 
   await agent(
     'Call iterate_validate for each command in iterate.config.yaml validation.commands and return all {command, exitCode} results.',
@@ -209,6 +226,7 @@ return {
 Key rules for normal mode:
 - Fixers are the ONLY agents allowed to write files; reviewers read only. Architectural findings are reported, never auto-fixed.
 - Aggregate the current round deterministically (\`report.findings\`) before fixing, so fixes act on deduped/filtered/sorted findings.
+- Apply atomic fixes **per file**: one fixer agent handles all findings for a given file serially, so the same file is never edited concurrently; different files are fixed in parallel.
 - Validate after every round of fixes; validation results are logged, not silently dropped.
 - Stop when a round produces nothing to fix (converged) or maxReviewRounds is reached.
 - Every round and the final report go to the append-only decision log.
@@ -218,10 +236,10 @@ Key rules for normal mode:
   "severity": "critical" | "high" | "medium" | "low", "summary": string (one line),
   "failure_scenario": string (how/when it fails), "suggested_fix": string (the concrete fix),
   "is_atomic": boolean (true if fix ≤ max_lines within a single file/function) }
-Atomic = is_atomic true (single file, single function, ≤20 lines change). Architectural = everything else.
+Atomic = is_atomic true (single file, single function, ≤ config.atomic.max_lines lines change). Architectural = everything else.
 
 ### Workflow meta
 Always pass \`meta: { name: "iterate", description: "Autonomous iterate loop" }\`.
 
 Always end with a clear summary: total findings, count by severity, fixes applied (normal) or convergence stats (dry-run), and remaining architectural findings.
-`
+`

package/src/tools/config.ts

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { loadEffectiveConfig, validateConfig } from '../config-loader.ts'
+import { loadEffectiveConfig, validateConfig, resolveProjectRoot } from '../config-loader.ts'
 
 /**
  * Register the `iterate_config` tool.
@@ -53,7 +53,11 @@ export function registerConfigTool(ctx: { tools: { register: (def: ReturnType<ty
       },
 
       async execute(args) {
-        const projectRoot = args.path ?? process.cwd()
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) {
+          return { found: false, error: resolved.reason }
+        }
+        const projectRoot = resolved.root
         // Effective config = defaults (Master) merged with any project-root
         // overrides. Never null: a project without a config file runs on the
         // built-in defaults, so the workflow stays usable out of the box.

package/src/tools/context.ts

@@ -2,6 +2,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { join, dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { defineTool } from '@deepseek-ai/dsh-tools'
+import { resolveProjectRoot } from '../config-loader.ts'
 
 /** How many ancestor directories we walk up looking for a SKILL.md. */
 const MAX_SKILL_DIR_LOOKUP_DEPTH = 12
@@ -115,6 +116,7 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
             skill: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             project: { oneOf: [{ type: 'string' }, { type: 'null' }] },
             skillSource: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            error: { type: 'string' },
             searched: { type: 'array', items: { type: 'string' } },
           },
         },
@@ -130,7 +132,11 @@ export function registerContextTool(ctx: { tools: { register: (def: ReturnType<t
       },
 
       async execute(args) {
-        const projectRoot = args.path ?? process.cwd()
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) {
+          return { found: false, error: resolved.reason, searched: [] }
+        }
+        const projectRoot = resolved.root
         const requested = (args.files ?? '')
           .split(',')
           .map((s) => s.trim().toLowerCase())

package/src/tools/decision-log.ts

@@ -2,6 +2,7 @@ import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { resolveProjectRoot } from '../config-loader.ts'
 import type { DecisionLogEntry } from '../types.ts'
 
 const LOG_DIR = '.iterate'
@@ -116,7 +117,11 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
       },
 
       async execute(args) {
-        const projectRoot = args.path ?? process.cwd()
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) {
+          return { operation: args.operation, error: resolved.reason }
+        }
+        const projectRoot = resolved.root
 
         if (args.operation === 'read') {
           const entries = readEntries(projectRoot)

package/src/tools/review.ts

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { JsonValue } from '@deepseek-ai/dsh-session'
-import { loadEffectiveConfig } from '../config-loader.ts'
+import { loadEffectiveConfig, resolveProjectRoot } from '../config-loader.ts'
 import { buildReviewPlan, buildReviewReport } from '../review.ts'
 import { buildFinalReviewReport, metaReviewReport } from '../meta-review.ts'
 import type { KnownIntentional, ReviewFinding, ReviewReport, ReviewRound } from '../types.ts'
@@ -98,7 +98,11 @@ export function registerReviewTool(ctx: { tools: { register: (def: ReturnType<ty
       },
 
       async execute(args) {
-        const projectRoot = args.path ?? process.cwd()
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) {
+          return { operation: args.operation, error: resolved.reason }
+        }
+        const projectRoot = resolved.root
         // Effective config = defaults merged with project overrides. Never
         // null, so `plan`/`aggregate` work even without a config file.
         const { config } = loadEffectiveConfig(projectRoot)

package/src/tools/validate.ts

@@ -1,9 +1,29 @@
 import { exec } from 'node:child_process'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { loadEffectiveConfig, isCommandAllowed, flattenCommands } from '../config-loader.ts'
+import {
+  loadEffectiveConfig,
+  isCommandAllowed,
+  flattenCommands,
+  resolveProjectRoot,
+} from '../config-loader.ts'
 import type { ValidationResult } from '../types.ts'
 
 const DEFAULT_TIMEOUT_MS = 120_000
+/** Hard ceiling on a single validation command's runtime, so a model cannot
+ *  pin the tool open indefinitely via an unbounded `timeout` argument. */
+const MAX_TIMEOUT_MS = 600_000
+
+/**
+ * Clamp a caller-supplied timeout (ms) to a sane range.
+ * Non-finite / non-positive values fall back to the default; any value above
+ * the ceiling is capped. Pure function, unit-tested.
+ */
+export function clampTimeout(ms: number | undefined): number {
+  if (typeof ms !== 'number' || !Number.isFinite(ms) || ms <= 0) {
+    return DEFAULT_TIMEOUT_MS
+  }
+  return Math.min(ms, MAX_TIMEOUT_MS)
+}
 
 /**
  * Run a single shell command with timeout and return structured results.
@@ -107,10 +127,23 @@ export function registerValidateTool(ctx: { tools: { register: (def: ReturnType<
       },
 
       async execute(args) {
-        const projectRoot = args.path ?? process.cwd()
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) {
+          return {
+            allowed: false,
+            command: args.command,
+            exitCode: -1,
+            stdout: '',
+            stderr: '',
+            timedOut: false,
+            durationMs: 0,
+            rejectReason: resolved.reason,
+          }
+        }
+        const projectRoot = resolved.root
         // Effective config = defaults merged with project overrides. Never null.
         const { config, source } = loadEffectiveConfig(projectRoot)
-        const timeout = args.timeout ?? DEFAULT_TIMEOUT_MS
+        const timeout = clampTimeout(args.timeout)
 
         // Only commands predefined in validation.commands may run — the
         // user trusts exactly these, and nothing else. This replaces the