iterate-plugin 2.9.4 → 2.11.0

package/README.md

@@ -23,7 +23,7 @@
 
 `iterate-plugin` is the [iterate](https://github.com/jingzhao-l/iterate-skill) integration for the [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) desktop client. It brings iterate's review loop (review → triage → fix → validate → converge) directly into the dsh UI, offering **autonomous closed-loop code iteration** (normal mode) and **dry-run read-only multi-round review**.
 
-Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage panel, convergence dashboard, stats card, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem (skill / headless engine) — zero migration cost.
+Besides 13 pure-function tools, it ships a **build-free Web UI layer** (triage panel, convergence dashboard, stats card, theme skin, etc.) that plugs straight into dsh's existing UI slots. Configuration (`iterate.config.yaml` and the review dimensions) is identical across the other two components of the iterate ecosystem ([skill](https://github.com/jingzhao-l/iterate-skill) / [headless engine](https://github.com/jingzhao-l/iterate-harness)) — zero migration cost.
 
 ## Features
 

package/README.zh-CN.md

@@ -23,7 +23,7 @@
 
 `iterate-plugin` 是 [iterate](https://github.com/jingzhao-l/iterate-skill) 项目在 [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness) 桌面客户端中的落地插件。它把 iterate 的开环审查闭环（review → triage → fix → validate → 收敛）直接带进 dsh 的界面：提供**自治闭环代码迭代**（normal 模式）与 **dry-run 纯多轮审查**（只读）两种能力。
 
-除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（技能 / 无头引擎）完全一致，迁移零成本。
+除 13 个纯函数工具外，还内置一套**免构建的 Web UI 层**（分诊面板、收敛看板、统计卡片、主题皮肤等），直接挂在 dsh 客户端的既有 UI 槽位上。配置方式（`iterate.config.yaml` 与审查维度）与迭代生态的另外两个组件（[技能](https://github.com/jingzhao-l/iterate-skill) / [无头引擎](https://github.com/jingzhao-l/iterate-harness)）完全一致，迁移零成本。
 
 ## 特性
 

package/dist/config-loader.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve, sep } from 'node:path';
 import yaml from 'js-yaml';
@@ -72,6 +72,11 @@ export function mergeConfig(base, override) {
     for (const [key, value] of Object.entries(override)) {
         if (value === undefined)
             continue;
+        // Prototype-pollution guard: a YAML `__proto__`/`constructor`/`prototype`
+        // key must never be plain-assigned — js-yaml stores __proto__ as an own
+        // data property, and `out[key] = value` would invoke the __proto__ setter.
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+            continue;
         const baseValue = out[key];
         if (baseValue &&
             typeof baseValue === 'object' &&
@@ -223,8 +228,14 @@ function effectiveCwd(sessionCwd) {
         if (encoded && encoded.startsWith('--') && encoded.endsWith('--')) {
             try {
                 const decoded = decodeURIComponent(encoded.slice(2, -2).replace(/~/g, '%'));
-                if (decoded && decoded.startsWith(sep))
-                    return decoded;
+                // The workspace encoding drops the leading root separator (`/Volumes/…`
+                // → `Volumes-…`), so re-attach it when absent. `~<hex>` → `%<hex>` is
+                // the documented percent spelling; '-' doubles as the '/' separator, so
+                // literal dashes in a path cannot round-trip — verify the result exists
+                // and fall through otherwise.
+                const candidate = decoded && !decoded.startsWith(sep) ? sep + decoded : decoded;
+                if (candidate && candidate.startsWith(sep) && existsSync(candidate))
+                    return candidate;
             }
             catch {
                 // malformed encoding — fall through to cwd

package/dist/config-write.js

@@ -9,7 +9,7 @@
  * 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 { copyFileSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import yaml from 'js-yaml';
 /** Config file name (must match config-loader). */
@@ -161,14 +161,17 @@ export function writeConfigFile(projectRoot, config) {
         writeFileSync(configPath, yaml.dump(config, { noRefs: true }), 'utf-8');
     }
     catch (err) {
+        let rollbackError = '';
         try {
             if (backupPath)
                 copyFileSync(backupPath, configPath);
+            else if (existsSync(configPath))
+                rmSync(configPath, { force: true });
         }
-        catch {
-            // Rollback failure is reported, never swallowed silently.
+        catch (rbErr) {
+            rollbackError = `; rollback also failed: ${String(rbErr)}`;
         }
-        return { ok: false, error: `failed to write config: ${String(err)}` };
+        return { ok: false, error: `failed to write config: ${String(err)}${rollbackError}` };
     }
     return { ok: true, backupPath };
 }

package/dist/evidence.js

@@ -22,10 +22,17 @@
  * The pure math (`countLines`, `verifyLineBounds`) is separated from the
  * filesystem half (`verifyFinding`) to stay unit-testable without touching disk.
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
 /** Sentinel for whole-file findings (line 0 or omitted means the whole file). */
 export const WHOLE_FILE_LINE = 0;
+/**
+ * Hard cap on a single evidence file read. `verifyFinding` only needs the
+ * line count + a NUL check; reading an unbounded file (or a device file
+ * reached through a symlink) is a memory/hang hazard, so anything larger is
+ * treated as not line-addressable.
+ */
+const MAX_EVIDENCE_BYTES = 10 * 1024 * 1024;
 /** Number of physical lines in `text`. A trailing newline does not add a line. */
 export function countLines(text) {
     if (text === '')
@@ -51,6 +58,22 @@ export function resolveWithin(root, rel) {
         return null;
     return resolved;
 }
+/** True when `candidate` is `root` itself or lexically inside `root`. */
+function isWithin(root, candidate) {
+    if (candidate === root)
+        return true;
+    const prefix = root.endsWith(sep) ? root : root + sep;
+    return candidate.startsWith(prefix);
+}
+/** best-effort realpath; falls back to the lexical path on any failure. */
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 /**
  * Pure check that `line` (if anchored) exists in `text`.
  * Whole-file findings (undefined/0) are always bounds-valid.
@@ -79,6 +102,49 @@ export function verifyFinding(root, input, opts = {}) {
             error: 'file_not_found',
         };
     }
+    // Symlink containment: resolveWithin is lexical only, but existsSync /
+    // readFileSync follow symlinks. Verify the REAL path stays inside the REAL
+    // project root so a finding path can never read (or line-count) a file
+    // outside the project via a symlinked directory or file.
+    const rootReal = safeRealpath(root);
+    const real = safeRealpath(resolved);
+    if (!isWithin(rootReal, real)) {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    // Regular-file + size guard: a directory, device file (/dev/zero), FIFO or
+    // multi-GB file is not a line-addressable text target. statSync follows
+    // symlinks, so a link to a device still lands here and is rejected.
+    let st;
+    try {
+        st = statSync(resolved);
+    }
+    catch {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'file_not_found',
+        };
+    }
+    if (!st.isFile() || st.size > MAX_EVIDENCE_BYTES) {
+        return {
+            file: relFile,
+            line,
+            lineTotal: null,
+            resolvedPath: resolved,
+            verified: false,
+            error: 'line_out_of_range',
+        };
+    }
     let raw;
     try {
         raw = readFileSync(resolved);

package/dist/git-scope.js

@@ -24,14 +24,31 @@ import { execFile } from 'node:child_process';
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 /**
- * Parse `git diff --name-only` stdout into a list of relative paths.
- * Pure: strips blank lines, trims whitespace, drops quotes (git can quote
- * paths with special characters).
+ * Parse `git diff --name-only -z` stdout into a list of relative paths.
+ * Pure. NUL-delimited mode is machine-safe (handles any filename); when no
+ * NUL is present (callers that did not pass -z) fall back to newline-split
+ * with C-style quote/escape unescaping for core.quotePath output.
  */
 export function parseChangedFiles(stdout) {
+    if (stdout.includes('\0')) {
+        return stdout.split('\0').map((s) => s.trim()).filter((s) => s.length > 0);
+    }
     return stdout
         .split('\n')
-        .map((line) => line.trim().replace(/^"|"$/g, ''))
+        .map((line) => {
+        const trimmed = line.trim();
+        // git core.quotePath wraps paths with special characters in "..."; the
+        // content uses C-style escapes (\" \\ \t \n and \ooo octal for non-ASCII).
+        const quoted = trimmed.match(/^"(.*)"$/);
+        if (!quoted)
+            return trimmed;
+        return quoted[1]
+            .replace(/\\"/g, '"')
+            .replace(/\\\\/g, '\\')
+            .replace(/\\t/g, '\t')
+            .replace(/\\n/g, '\n')
+            .replace(/\\([0-7]{3})/g, (_m, oct) => String.fromCharCode(parseInt(oct, 8)));
+    })
         .filter((line) => line.length > 0);
 }
 /**
@@ -90,9 +107,21 @@ export function runGit(args, cwd) {
  * plan because git is unavailable.
  */
 export async function resolveChangedFiles(root, targetBranch) {
-    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', targetBranch, '--'], root);
+    // Option-injection guard: a branch name starting with '-' would be parsed by
+    // git as an option (e.g. --output=...), not a ref. Reject it outright.
+    if (typeof targetBranch !== 'string' || targetBranch.trim() === '' || targetBranch.startsWith('-')) {
+        return {
+            scope: 'full',
+            changedFiles: [],
+            fallbackToFull: true,
+            error: `invalid target branch "${String(targetBranch)}"`,
+        };
+    }
+    // -z: NUL-delimited names — machine-safe for any filename (spaces, quotes,
+    // non-ASCII), and never confused with option-like content.
+    const { ok, stdout, stderr } = await runGit(['diff', '--name-only', '-z', targetBranch, '--'], root);
     if (!ok) {
-        const reason = stderr.trim() || `git diff --name-only ${targetBranch} failed`;
+        const reason = stderr.trim() || `git diff --name-only -z ${targetBranch} failed`;
         return { scope: 'full', changedFiles: [], fallbackToFull: true, error: reason };
     }
     const existing = filterExistingFiles(root, parseChangedFiles(stdout));

package/dist/meta-review.js

@@ -14,8 +14,13 @@
  * lives here.
  */
 import { sortFindings } from "./review.js";
-/** Number of distinct consistency checks performed by `metaReviewReport`. */
-export const META_REVIEW_CHECKS = 6;
+/**
+ * Number of distinct consistency checks performed by `metaReviewReport`.
+ * The check set is: COUNT_MATCH, SEVERITY_SUM, DIMENSION_SUM, DIMENSION_UNKNOWN,
+ * SORT_ORDER, CONVERGENCE_SUM, CONVERGENCE_FLAG, ROUND_NUMBER, ROUND_EMPTY,
+ * ROUND_GAP.
+ */
+export const META_REVIEW_CHECKS = 10;
 /**
  * How many uncovered scope files are listed in a COVERAGE_GAP hint before the
  * remainder is folded into a "+N more" suffix.
@@ -146,9 +151,18 @@ export function metaReviewReport(report) {
                 'which finding nothing new is the expected success signal.');
         }
     }
-    for (let i = 1; i <= rounds.length; i++) {
-        if (!seenRounds.has(i)) {
-            add('ROUND_GAP', 'medium', `Round ${i} is missing from the round sequence`, `rounds present: ${[...seenRounds].sort((a, b) => a - b).join(', ') || 'none'}.`);
+    // ROUND_GAP: only flag gaps WITHIN the range of actually-present round
+    // numbers. Non-contiguous starts (e.g. a resumed run beginning at round 5)
+    // and arbitrary round numbering are supported by the aggregate engine, so
+    // missing 1..N prefixes are NOT defects. Checks min..max of present rounds.
+    const present = [...seenRounds].sort((a, b) => a - b);
+    if (present.length > 0) {
+        const min = present[0];
+        const max = present[present.length - 1];
+        for (let i = min; i <= max; i++) {
+            if (!seenRounds.has(i)) {
+                add('ROUND_GAP', 'medium', `Round ${i} is missing from the round sequence`, `rounds present: ${present.join(', ')}.`);
+            }
         }
     }
     const passed = issues.length === 0;

package/dist/method-scope.js

@@ -70,6 +70,8 @@ const SIGNATURE_PATTERNS = [
 export function collectMethodSignatures(text) {
     const lines = text.split('\n');
     const out = [];
+    // Set lookup instead of scanning the growing array (O(S²) → O(S)).
+    const seen = new Set();
     for (let i = 0; i < lines.length; i++) {
         const raw = lines[i];
         const line = i + 1;
@@ -81,8 +83,10 @@ export function collectMethodSignatures(text) {
             if (!name || RESERVED_WORDS.has(name) || CALLABLE_NOISE.has(name))
                 continue;
             // Avoid two patterns claiming the same line (e.g. TS method + arrow).
-            if (out.some((s) => s.line === line && s.name === name))
+            const key = `${line}|${name}`;
+            if (seen.has(key))
                 break;
+            seen.add(key);
             out.push({ name, line });
             break;
         }

package/dist/review-scope.js

@@ -99,22 +99,25 @@ function collectChanged(changedFiles) {
     return [...out].sort();
 }
 function collectFull(root) {
-    // Deterministic recursive walk built on Node's fs; a code reviewer never
-    // anchors findings to lock files, images, or vendored builds.
+    // Deterministic iterative walk (explicit stack — unbounded recursion could
+    // overflow on pathologically deep trees); a code reviewer never anchors
+    // findings to lock files, images, or vendored builds.
     const out = [];
-    const walk = (dir) => {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
         let entries;
         try {
             entries = readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            return;
+            continue;
         }
         for (const entry of entries) {
             const abs = join(dir, entry.name);
             if (entry.isDirectory()) {
                 if (!isIgnoredDir(entry.name))
-                    walk(abs);
+                    stack.push(abs);
                 continue;
             }
             if (!entry.isFile())
@@ -124,13 +127,14 @@ function collectFull(root) {
             const rel = abs.startsWith(root + SEP) ? abs.slice(root.length + 1) : abs;
             out.push(rel.split(SEP).join(SEP));
         }
-    };
-    walk(root);
+    }
     return out.sort();
 }
 /** Split `files` into stable batches, keeping directory runs together. */
 export function chunkFiles(files, perChunk) {
-    const size = perChunk === undefined || perChunk < 1 ? DEFAULT_SCOPE_CHUNK_SIZE : perChunk;
+    // Number.isFinite: NaN fails `perChunk < 1` and would yield one unbounded
+    // chunk (current.length >= NaN is never true).
+    const size = Number.isFinite(perChunk) && perChunk >= 1 ? perChunk : DEFAULT_SCOPE_CHUNK_SIZE;
     const ordered = [...files].sort();
     const chunks = [];
     let current = [];

package/dist/review.js

@@ -35,10 +35,12 @@ export function sortFindings(findings) {
         const bySeverity = rankA - rankB;
         if (bySeverity !== 0)
             return bySeverity;
-        const byFile = a.file.localeCompare(b.file);
+        // Defensive coercion: `file`/`line` can be wrong-typed when schema
+        // validation is disabled — String()/Number() keep the comparator total.
+        const byFile = String(a.file ?? '').localeCompare(String(b.file ?? ''));
         if (byFile !== 0)
             return byFile;
-        return (a.line ?? 0) - (b.line ?? 0);
+        return (Number(a.line) || 0) - (Number(b.line) || 0);
     });
 }
 /** Normalize a summary so near-identical duplicates collapse to one key. */
@@ -48,9 +50,15 @@ export function normalizeSummary(summary) {
         .toLowerCase()
         .replace(/[\s\n\t]+/g, ' ');
 }
-/** Dedupe key: same file + same dimension + similar summary. */
+/**
+ * Dedupe key: same file + same dimension + similar summary + explicit line.
+ * Including the line keeps two genuine issues with identical wording at
+ * different locations from collapsing into one (the line is omitted only when
+ * neither side anchors one, i.e. whole-file findings).
+ */
 export function findingKey(f) {
-    return `${f.file}|${f.dimension}|${normalizeSummary(f.summary)}`;
+    const line = typeof f.line === 'number' && f.line > 0 ? f.line : 0;
+    return `${f.file}|${f.dimension}|${line}|${normalizeSummary(f.summary)}`;
 }
 /**
  * Remove duplicate findings within a list.
@@ -109,14 +117,22 @@ export function aggregateRounds(rounds, maxReviewRounds) {
     const firstRoundByKey = new Map();
     const merged = [];
     // Guard: round numbers are expected to be positive integers. Skip malformed
-    // entries defensively rather than letting `firstRoundByKey` key on NaN/0.
+    // entries defensively rather than letting `firstRoundByKey` key on NaN/0 or
+    // crashing on null / non-array findings.
+    // Hard ceiling: round numbers are model-authored JSON; an absurd round (e.g.
+    // 1e9) would otherwise allocate an array of that size below (OOM). Round
+    // numbers above the configured cap are clamped to the cap.
     let maxRound = 0;
+    const roundCap = Math.max(1, maxReviewRounds);
     for (const round of rounds) {
+        if (!round || typeof round !== 'object')
+            continue;
         if (typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
             continue;
+        const findings = Array.isArray(round.findings) ? round.findings : [];
         if (round.round > maxRound)
             maxRound = round.round;
-        for (const f of round.findings) {
+        for (const f of findings) {
             const key = findingKey(f);
             if (seen.has(key))
                 continue;
@@ -125,8 +141,10 @@ export function aggregateRounds(rounds, maxReviewRounds) {
             merged.push(f);
         }
     }
+    // Clamp the allocation bound so a hostile round number cannot OOM the tool.
+    const effectiveMax = Math.min(maxRound, Math.max(1, roundCap * 2));
     const findingsByRound = [];
-    for (let r = 1; r <= maxRound; r++) {
+    for (let r = 1; r <= effectiveMax; r++) {
         let count = 0;
         for (const key of firstRoundByKey.keys()) {
             if (firstRoundByKey.get(key) === r)
@@ -143,11 +161,20 @@ export function computeConvergence(rounds, maxReviewRounds) {
     const { findingsByRound } = aggregateRounds(rounds, maxReviewRounds);
     const totalRounds = rounds.length;
     // `findingsByRound` is indexed by the actual round number (round r → index
-    // r-1), so convergence must read the LAST PRESENT round's count using its
-    // reported round number — not `totalRounds - 1`, which is only valid for
-    // contiguous 1..N round numbers.
-    const lastRound = totalRounds > 0 ? rounds[totalRounds - 1].round : 0;
-    const lastRoundCount = lastRound > 0 ? (findingsByRound[lastRound - 1] ?? 0) : 0;
+    // r-1), sized to the highest present round (clamped). Convergence must read
+    // the HIGHEST PRESENT round's count — not the last array element (rounds
+    // may arrive unsorted) and not `totalRounds - 1` (only valid for contiguous
+    // 1..N). The count index is bounded by the array length aggregateRounds
+    // actually allocated.
+    let lastRound = 0;
+    for (const round of rounds) {
+        if (!round || typeof round.round !== 'number' || !Number.isInteger(round.round) || round.round < 1)
+            continue;
+        if (round.round > lastRound)
+            lastRound = round.round;
+    }
+    const idx = Math.min(lastRound, findingsByRound.length) - 1;
+    const lastRoundCount = idx >= 0 ? (findingsByRound[idx] ?? 0) : 0;
     const converged = totalRounds > 0 && lastRoundCount === 0;
     return {
         totalRounds,
@@ -193,8 +220,9 @@ function summarize(findings) {
 export function buildReviewReport(input) {
     // 1. Filter known-intentional per round (before cross-round dedupe).
     const filteredRounds = input.rounds.map((r) => ({
-        round: r.round,
-        findings: filterKnownIntentional(r.findings, input.knownIntentional),
+        round: typeof r?.round === 'number' ? r.round : 0,
+        findings: filterKnownIntentional(Array.isArray(r?.findings) ? r.findings : [], input.knownIntentional),
+        readFiles: Array.isArray(r?.readFiles) ? r.readFiles : [],
     }));
     // 2. Cross-round dedupe + per-round "first seen" tracking.
     const { findings, findingsByRound } = aggregateRounds(filteredRounds, input.maxReviewRounds);
@@ -221,6 +249,9 @@ export function buildReviewReport(input) {
         maxReviewRounds: input.maxReviewRounds,
         rounds: filteredRounds,
         findings: sorted,
+        // Aggregate of every round's self-reported reads, so the meta-review
+        // coverage gate can compare against the assigned inventory.
+        readFiles: [].concat(...filteredRounds.map((r) => r.readFiles ?? [])),
         convergence: {
             totalRounds: filteredRounds.length,
             findingsByRound,
@@ -394,8 +425,8 @@ export function validateFindingsSchema(input) {
  */
 export function validateRoundsSchema(rounds) {
     return rounds.map((r) => {
-        const issues = validateFindingsSchema(r.findings);
-        return { round: r.round, valid: issues.length === 0, issues };
+        const issues = validateFindingsSchema(Array.isArray(r?.findings) ? r.findings : []);
+        return { round: typeof r?.round === 'number' ? r.round : 0, valid: issues.length === 0, issues };
     });
 }
 /**
@@ -411,19 +442,25 @@ export function validateRoundsSchema(rounds) {
  */
 export function sanitizeRounds(rounds, schemaValidation) {
     return rounds.map((r, i) => {
+        // Defensive: malformed rounds must never crash the deterministic core.
+        const findings = Array.isArray(r?.findings) ? r.findings : [];
+        const roundNo = typeof r?.round === 'number' ? r.round : 0;
+        const readFiles = Array.isArray(r?.readFiles) ? r.readFiles : [];
         if (schemaValidation) {
             const issues = schemaValidation[i]?.issues ?? [];
             if (issues.some((iss) => iss.index === -1))
-                return { round: r.round, findings: [] };
+                return { round: roundNo, findings: [], readFiles };
             const bad = new Set(issues.map((iss) => iss.index));
             return {
-                round: r.round,
-                findings: r.findings.filter((_, fi) => !bad.has(fi)),
+                round: roundNo,
+                findings: findings.filter((_, fi) => !bad.has(fi)),
+                readFiles,
             };
         }
         return {
-            round: r.round,
-            findings: r.findings.filter((f) => Boolean(f) && typeof f === 'object' && !Array.isArray(f)),
+            round: roundNo,
+            findings: findings.filter((f) => Boolean(f) && typeof f === 'object' && !Array.isArray(f)),
+            readFiles,
         };
     });
 }
@@ -435,6 +472,9 @@ export function sanitizeRounds(rounds, schemaValidation) {
 export function reviewerTaskPrompt(input) {
     const parts = [];
     parts.push(`You are the "${input.dimension}" reviewer for the iterate review.`, `Goal: ${input.goal}`, `Scope: ${input.scope === 'full' ? 'entire codebase' : 'changed files only'}.`);
+    if (input.focus) {
+        parts.push(`FOCUS: ${input.focus}`);
+    }
     if (input.scopeFiles && input.scopeFiles.length > 0) {
         parts.push('COVERAGE RULE (mandatory): below is the exact file inventory you are ' +
             'assigned to review. You MUST open EVERY file in this inventory with ' +
@@ -465,9 +505,9 @@ export function reviewerTaskPrompt(input) {
         'disqualifying failure, and fabricated line numbers are treated as ' +
         'poisoned evidence. Anchor every finding to real code.');
     parts.push(`Return a JSON object: {"findings": [...], "readFiles": [...]}.`, `Each finding: dimension (must be "${input.dimension}"), file (relative path), ` +
-        'line (REQUIRED positive integer — the exact line you READ for an ' +
-        'anchored, line-targeted issue; use 0 for whole-file/module-level ' +
-        'issues), severity (critical/high/medium/low), summary (one line), ' +
+        'line (optional; the exact line you READ for a line-targeted issue; ' +
+        '0 or omitted for whole-file/module-level issues), ' +
+        'severity (critical/high/medium/low), summary (one line), ' +
         'failure_scenario (how/when it fails, backed by the code you actually ' +
         'read), suggested_fix (the concrete fix), ' +
         `is_atomic (true if the fix is <= ${input.maxLines} lines within a SINGLE file/function, else false).`, `Write summaries and details in ${input.outputLanguage}.`);
@@ -508,6 +548,17 @@ export function buildReviewPlan(input) {
         batches = [undefined];
     }
     const dimensionTasks = [];
+    // personalization.dimension_focus: [{dimension, focus}] — appended to the
+    // matching dimension's reviewer prompt.
+    const focusMap = new Map();
+    const pf = input.config.personalization;
+    if (pf && Array.isArray(pf.dimension_focus)) {
+        for (const entry of pf.dimension_focus) {
+            if (entry && typeof entry.dimension === 'string' && typeof entry.focus === 'string' && entry.focus) {
+                focusMap.set(entry.dimension, entry.focus);
+            }
+        }
+    }
     for (const d of dimensions) {
         batches.forEach((batch, index) => {
             const dimensionId = batches.length === 1 ? d : `${d}#${index + 1}`;
@@ -523,6 +574,7 @@ export function buildReviewPlan(input) {
                     maxLines,
                     changedFiles: effectiveChangedOnly ? changedFiles : undefined,
                     scopeFiles: batch,
+                    focus: focusMap.get(d),
                 }),
                 findingsSchema: findingsSchema(),
             });

package/dist/skill-prompt.js

@@ -88,14 +88,28 @@ for (let r = 1; r <= maxRounds; r++) {
     const nudge = retries > 0
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
-    const raw = await parallel(dims.map(dim => () => agent(
-      'Review dimension "' + dim + '".' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
-      ' Already-known findings (do NOT re-report): ' +
-      JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.',
-      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
-    )))
-    const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+    const raw = await parallel(dims.map(dim => () => {
+      // Pass the plan's full per-dimension reviewerPrompt (goal, COVERAGE RULE
+      // with the assigned file inventory, EVIDENCE RULE, output language) and
+      // append the round-specific context — the reviewers must receive the
+      // file inventory or the coverage machinery has nothing to enforce.
+      const meta = plan.dimensions.find(x => x.id === dim)
+      const base = (meta && typeof meta.reviewerPrompt === 'string' && meta.reviewerPrompt)
+        ? meta.reviewerPrompt
+        : 'Review dimension "' + dim + '".'
+      const extra =
+        (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
+        '\\n Already-known findings (do NOT re-report): ' +
+        JSON.stringify(known) + nudge + '\\nReturn the findings JSON object.'
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+    }))
+    const thisRound = {
+      round: r,
+      findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])),
+      // readFiles are threaded through so the aggregate/meta-review coverage
+      // gate can compare self-reported reads against the assigned inventory.
+      readFiles: [].concat(...raw.map(x => x && Array.isArray(x.readFiles) ? x.readFiles : [])),
+    }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
     // Deterministic aggregate: cross-round dedupe + known_intentional filter + severity sort.
     agg = await agent(
@@ -228,6 +242,11 @@ let failedCommands = []
 phase('loop')
 for (let r = startRound; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — review current state, fix atomics via iterate_fix, validate')
+  // Audit-trail: record the round start (SKILL.md Phase 4 requires per-round records).
+  await agent(
+    'Call iterate_decision_log({operation:"append", type:"round_start", round:' + r + ', data:{maxRounds:' + maxRounds + ', fixedSoFar:' + fixedCount + '}})',
+    Object.assign({ label: 'log:start:r' + r }, backend)
+  )
   let agg = null
   let schemaInvalid = false
   let retries = 0
@@ -236,13 +255,24 @@ for (let r = startRound; r <= maxRounds; r++) {
     const nudge = retries > 0
       ? '\\nSTRICT JSON REQUIRED: your previous output failed schema validation. Return ONLY a JSON object {"findings":[...]} where EVERY finding has dimension, file, line (non-negative integer; 0 = whole-file), severity (critical|high|medium|low), summary, failure_scenario, suggested_fix, is_atomic (boolean).'
       : ''
-    const raw = await parallel(dims.map(dim => () => agent(
-      'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed). ' +
-      (attachments.length > 0 ? ' User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
-      'Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.',
-      Object.assign({ label: 'review:' + dim + ':r' + r, schema: plan.dimensions.find(x => x.id === dim).findingsSchema }, backend)
-    )))
-    const thisRound = { round: r, findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])) }
+    const raw = await parallel(dims.map(dim => () => {
+      // Pass the plan's full per-dimension reviewerPrompt (COVERAGE RULE with
+      // the assigned file inventory, EVIDENCE RULE, output language) plus the
+      // round-specific context.
+      const meta = plan.dimensions.find(x => x.id === dim)
+      const base = (meta && typeof meta.reviewerPrompt === 'string' && meta.reviewerPrompt)
+        ? meta.reviewerPrompt
+        : 'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed).'
+      const extra =
+        (attachments.length > 0 ? '\\n User-attached images are part of the evidence; use their descriptions when judging (you see the metadata/descriptions below, not the pixels): ' + JSON.stringify(attachments) + '.' : '') +
+        '\\n Do NOT re-report already-known architectural findings: ' + JSON.stringify(architectural) + nudge + '\\nReturn the findings JSON object.'
+      return agent(base + extra, Object.assign({ label: 'review:' + dim + ':r' + r, schema: meta.findingsSchema }, backend))
+    }))
+    const thisRound = {
+      round: r,
+      findings: [].concat(...raw.map(x => x && x.findings ? x.findings : [])),
+      readFiles: [].concat(...raw.map(x => x && Array.isArray(x.readFiles) ? x.readFiles : [])),
+    }
     if (rounds.length >= r) rounds[r - 1] = thisRound; else rounds.push(thisRound)
 
     // Deterministic dedupe / known_intentional filter / severity sort for this round.