iterate-plugin 2.3.6 → 2.4.0

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'
@@ -81,6 +82,16 @@ export function registerDecisionLogTool(ctx: { tools: { register: (def: ReturnTy
           description:
             'Entry type (required for append): round_start, review_result, atomic_fix, ' +
             'architectural_fix, revert, validation, decision, report.',
+          enum: [
+            'round_start',
+            'review_result',
+            'atomic_fix',
+            'architectural_fix',
+            'revert',
+            'validation',
+            'decision',
+            'report',
+          ],
         },
         round: {
           type: 'integer',
@@ -116,7 +127,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/triage.ts

@@ -0,0 +1,370 @@
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import yaml from 'js-yaml'
+import { resolveProjectRoot } from '../config-loader.ts'
+import type { KnownIntentional } from '../types.ts'
+
+const CONFIG_FILE = 'iterate.config.yaml'
+
+/** Personalization key that holds the known-intentional list. */
+const PERSONALIZATION_KEY = 'personalization'
+const KNOWN_INTENTIONAL_KEY = 'known_intentional'
+
+/** Whole-file marker line (matches review.ts filterKnownIntentional semantics). */
+const WHOLE_FILE_LINE = 0
+
+// ─── Pure helpers (exported for unit tests) ─────────────────────────────────
+
+/**
+ * Normalize a caller-supplied `line` value.
+ * Returns a positive integer, or `undefined` when the value is absent,
+ * non-numeric, or non-positive (which is the "whole file" semantics).
+ *
+ * @param {unknown} line
+ * @returns {number | undefined}
+ */
+export function normalizeEntryLine(line: unknown): number | undefined {
+  if (typeof line !== 'number' || !Number.isInteger(line)) return undefined
+  if (line <= 0) return undefined
+  return line
+}
+
+/**
+ * Validate an array of triage entries. Each entry must be an object with
+ * non-empty string `file` / `dimension` / `reason`, and an optional positive
+ * integer `line`.
+ *
+ * @param {unknown} entries
+ * @returns {string[]} Validation error messages (empty when valid).
+ */
+export function validateTriageEntries(entries: unknown): string[] {
+  const errors: string[] = []
+  if (!Array.isArray(entries)) {
+    errors.push('entries must be an array')
+    return errors
+  }
+  for (let i = 0; i < entries.length; i++) {
+    const prefix = `entries[${i}]`
+    const e = entries[i]
+    if (!e || typeof e !== 'object') {
+      errors.push(`${prefix} must be an object`)
+      continue
+    }
+    const entry = e as Record<string, unknown>
+    if (typeof entry.file !== 'string' || entry.file.trim().length === 0) {
+      errors.push(`${prefix}.file must be a non-empty string`)
+    }
+    if (typeof entry.dimension !== 'string' || entry.dimension.trim().length === 0) {
+      errors.push(`${prefix}.dimension must be a non-empty string`)
+    }
+    if (typeof entry.reason !== 'string' || entry.reason.trim().length === 0) {
+      errors.push(`${prefix}.reason must be a non-empty string`)
+    }
+    if (entry.line !== undefined && normalizeEntryLine(entry.line) === undefined) {
+      errors.push(`${prefix}.line must be a positive integer when present`)
+    }
+  }
+  return errors
+}
+
+/**
+ * Build the dedupe key for a known-intentional entry.
+ * Semantics mirror review.ts filterKnownIntentional: a whole-file entry
+ * (`line` 0/undefined) is distinct from a line-specific one.
+ *
+ * @param {KnownIntentional} entry
+ * @returns {string}
+ */
+export function entryKey(entry: KnownIntentional): string {
+  const line = normalizeEntryLine(entry.line) ?? WHOLE_FILE_LINE
+  return `${entry.file}|${entry.dimension}|${line}`
+}
+
+/**
+ * Merge incoming entries into the existing known-intentional list.
+ * Existing entries are never mutated; incoming entries whose key already
+ * exists are skipped. Returns the merged list plus add/skip counts.
+ *
+ * @param {KnownIntentional[]} existing
+ * @param {KnownIntentional[]} incoming
+ * @returns {{ merged: KnownIntentional[], added: number, skipped: number }}
+ */
+export function mergeKnownIntentional(
+  existing: KnownIntentional[],
+  incoming: KnownIntentional[],
+): { merged: KnownIntentional[]; added: number; skipped: number } {
+  const seen = new Set<string>()
+  const merged: KnownIntentional[] = []
+  for (const entry of existing) {
+    const key = entryKey(entry)
+    if (!seen.has(key)) {
+      seen.add(key)
+      merged.push(entry)
+    }
+  }
+  let added = 0
+  let skipped = 0
+  for (const entry of incoming) {
+    const key = entryKey(entry)
+    if (seen.has(key)) {
+      skipped++
+      continue
+    }
+    seen.add(key)
+    merged.push(entry)
+    added++
+  }
+  return { merged, added, skipped }
+}
+
+/**
+ * Build a NEW config object with `personalization.known_intentional` set to
+ * the merged entries. All other top-level fields are preserved unchanged.
+ * Returns a deep-enough copy so the caller can serialize it safely.
+ *
+ * @param {Record<string, unknown>} config
+ * @param {KnownIntentional[]} entries
+ * @returns {Record<string, unknown>}
+ */
+export function buildConfigWithKnownIntentional(
+  config: Record<string, unknown>,
+  entries: KnownIntentional[],
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...config }
+  const personalization =
+    next[PERSONALIZATION_KEY] && typeof next[PERSONALIZATION_KEY] === 'object'
+      ? { ...(next[PERSONALIZATION_KEY] as Record<string, unknown>) }
+      : {}
+  personalization[KNOWN_INTENTIONAL_KEY] = entries
+  next[PERSONALIZATION_KEY] = personalization
+  return next
+}
+
+/** Read the raw known-intentional list from a config object (may be absent). */
+export function readKnownIntentional(
+  config: Record<string, unknown>,
+): KnownIntentional[] {
+  const personalization = config[PERSONALIZATION_KEY]
+  if (!personalization || typeof personalization !== 'object') return []
+  const known = (personalization as Record<string, unknown>)[KNOWN_INTENTIONAL_KEY]
+  if (!Array.isArray(known)) return []
+  return known.filter(
+    (e): e is KnownIntentional =>
+      !!e &&
+      typeof e === 'object' &&
+      typeof (e as Record<string, unknown>).file === 'string',
+  )
+}
+
+/** Build a filesystem-safe backup suffix from the current time. */
+export function backupSuffix(now = new Date()): string {
+  return now.toISOString().replace(/[:.]/g, '-')
+}
+
+// ─── File I/O ───────────────────────────────────────────────────────────────
+
+/** Load the raw config object (empty when the file is missing). */
+function readConfigFile(configPath: string): Record<string, unknown> {
+  if (!existsSync(configPath)) return {}
+  const content = readFileSync(configPath, 'utf-8')
+  const parsed = yaml.load(content)
+  if (!parsed || typeof parsed !== 'object') {
+    // A config that exists but is not a YAML mapping must NOT be silently
+    // treated as empty: writing over it would destroy user data. Callers
+    // surface this as an error and refuse to write.
+    throw new Error('existing iterate.config.yaml is not a valid YAML mapping')
+  }
+  return parsed as Record<string, unknown>
+}
+
+/** Apply the triage entries: backup, merge, write, rollback on failure. */
+function applyEntries(
+  projectRoot: string,
+  incoming: KnownIntentional[],
+): {
+  ok: true
+  added: number
+  skipped: number
+  count: number
+  configPath: string
+  backupPath: string | null
+} | {
+  ok: false
+  error: string
+} {
+  const configPath = join(projectRoot, CONFIG_FILE)
+  let config: Record<string, unknown>
+  try {
+    config = readConfigFile(configPath)
+  } catch (err) {
+    // The file exists but is malformed — refuse to overwrite user data.
+    return { ok: false, error: `Failed to read config: ${String(err)}` }
+  }
+  const existing = readKnownIntentional(config)
+  const { merged, added, skipped } = mergeKnownIntentional(existing, incoming)
+  const nextConfig = buildConfigWithKnownIntentional(config, merged)
+
+  const hadFile = existsSync(configPath)
+  const backupPath = hadFile ? `${configPath}.bak-${backupSuffix()}` : null
+
+  if (backupPath) {
+    try {
+      copyFileSync(configPath, backupPath)
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Failed to create backup: ${String(err)}`,
+      }
+    }
+  }
+
+  const yamlText = yaml.dump(nextConfig, { noRefs: true })
+  try {
+    writeFileSync(configPath, yamlText, 'utf-8')
+  } catch (err) {
+    // Rollback: restore the backup (or delete the file we just created).
+    try {
+      if (backupPath) copyFileSync(backupPath, configPath)
+      else if (existsSync(configPath)) writeFileSync(configPath, '', 'utf-8')
+    } catch {
+      // Rollback failure is reported, not swallowed silently.
+    }
+    return {
+      ok: false,
+      error: `Failed to write config: ${String(err)}`,
+    }
+  }
+
+  return { ok: true, added, skipped, count: merged.length, configPath, backupPath }
+}
+
+/**
+ * Register the `iterate_triage` tool.
+ *
+ * Completes the findings-triage closed loop: the client triage panel marks
+ * findings as "known intentional" (a), and this tool writes those entries
+ * into `iterate.config.yaml` under `personalization.known_intentional` so the
+ * next review round filters them out (review.ts filterKnownIntentional).
+ *
+ * Operations:
+ *  - `apply`: merge validated entries into the config (dedupe by
+ *             file|dimension|line), with an automatic timestamped backup and
+ *             rollback if the write fails.
+ *  - `list`:  read back the current known_intentional entries.
+ */
+export function registerTriageTool(ctx: { tools: { register: (def: ReturnType<typeof defineTool>) => void } }): void {
+  ctx.tools.register(
+    defineTool({
+      name: 'iterate_triage',
+      description:
+        'Manage `personalization.known_intentional` entries in iterate.config.yaml. ' +
+        'Use `apply` to write back triage verdicts (entries where the reviewer said "known intentional") so ' +
+        'future review rounds filter them out. Entries are deduped by file|dimension|line and the config is ' +
+        'backed up before writing. Use `list` to read the current entries. ' +
+        'The client browser cannot write files, so this tool is the write-back channel for the triage panel.',
+      parameters: {
+        operation: {
+          type: 'string',
+          required: true,
+          description: '"apply" to merge entries into the config, "list" to read them back.',
+          enum: ['apply', 'list'],
+        },
+        entries: {
+          type: 'json',
+          description:
+            'For `apply`: array of known-intentional entries, e.g. ' +
+            '[{"file":"src/a.ts","line":42,"dimension":"security","reason":"..."}]. ' +
+            'Each entry needs non-empty string file/dimension/reason; line is an optional positive integer ' +
+            '(omitted = whole file).',
+        },
+        path: {
+          type: 'string',
+          description: 'Project root directory (default: current working directory).',
+        },
+      },
+
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            operation: { type: 'string', required: true },
+            added: { type: 'integer' },
+            skipped: { type: 'integer' },
+            count: { type: 'integer' },
+            path: { type: 'string' },
+            backupPath: { type: 'string' },
+            entries: { type: 'json' },
+            errors: { type: 'array', items: { type: 'string' } },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [
+          { type: 'text', text: JSON.stringify(value, null, 2) },
+        ],
+      },
+
+      async execute(args) {
+        const resolved = resolveProjectRoot(args.path)
+        if (!resolved.ok) {
+          return { operation: args.operation, error: resolved.reason }
+        }
+        const projectRoot = resolved.root
+        const configPath = join(projectRoot, CONFIG_FILE)
+
+        if (args.operation === 'list') {
+          let config: Record<string, unknown>
+          try {
+            config = readConfigFile(configPath)
+          } catch (err) {
+            return { operation: 'list', error: `Failed to read config: ${String(err)}` }
+          }
+          const entries = readKnownIntentional(config)
+          return {
+            operation: 'list',
+            count: entries.length,
+            path: configPath,
+            entries: entries as unknown as JsonValue,
+          }
+        }
+
+        if (args.operation === 'apply') {
+          const validation = validateTriageEntries(args.entries)
+          if (validation.length > 0) {
+            return { operation: 'apply', errors: validation, error: 'Invalid entries.' }
+          }
+          const incoming = (args.entries as unknown[]).map((e) => {
+            const raw = e as Record<string, unknown>
+            return {
+              file: String(raw.file),
+              ...(normalizeEntryLine(raw.line) !== undefined
+                ? { line: normalizeEntryLine(raw.line) as number }
+                : {}),
+              dimension: String(raw.dimension),
+              reason: String(raw.reason),
+            } as KnownIntentional
+          })
+          const result = applyEntries(projectRoot, incoming)
+          if (!result.ok) {
+            return { operation: 'apply', error: result.error }
+          }
+          return {
+            operation: 'apply',
+            added: result.added,
+            skipped: result.skipped,
+            count: result.count,
+            path: result.configPath,
+            backupPath: result.backupPath ?? undefined,
+          }
+        }
+
+        return {
+          operation: args.operation,
+          error: 'Unknown operation. Use "apply" or "list".',
+        }
+      },
+    }),
+  )
+}

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