iterate-plugin 2.6.0 → 2.7.0

package/README.md

@@ -55,6 +55,16 @@ dsh plugin --profile web add iterate-plugin
 pnpm add iterate-plugin
 ```
 
+### 从 GitHub 安装（dsh 生态第三方安装方式）
+
+dsh 官方支持从 GitHub 插件仓库直接安装：`dsh plugin --profile web add "github:owner/repo#ref"`（仓库根即插件，声明 `dsh.bundle` 后自动启用）。本插件在 [iterate-plugin 独立仓库](https://github.com/jingzhao-l/iterate-plugin) 维护仓库根即插件的发布位，由主仓库通过 `git subtree` 同步，内容与 npm 包一致：
+
+```bash
+dsh plugin --profile web add "github:jingzhao-l/iterate-plugin#main"
+```
+
+安装完成后需重启 dsh 服务（建议 `dsh web --patch`）并刷新页面，宿主与客户端 UI 层才会加载。
+
 ### 本地开发 / 源码挂载
 
 ```bash

package/dist/config-loader.js

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

package/dist/config-write.js

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

package/dist/index.js

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

package/dist/meta-review.js

@@ -0,0 +1,181 @@
+/**
+ * Meta-review engine: review a ReviewReport and produce a final review report.
+ *
+ * This is the "纯反复审查" closing step: after the review loop converges on
+ * zero new findings, we don't just trust the aggregated report — we audit the
+ * report itself for internal consistency (counts, severity buckets, dimension
+ * sums, sort order, convergence math). The result is a deterministic
+ * `MetaReviewResult` plus a `FinalReviewReport` that pairs the source report
+ * with a verdict.
+ *
+ * Like `review.ts`, this module contains NO I/O and NO agent spawning — it is
+ * the pure, testable core. The workflow script (skill-prompt.ts) orchestrates
+ * the actual subagent-driven meta-review critique; all deterministic math
+ * lives here.
+ */
+import { sortFindings } from "./review.js";
+/** Number of distinct consistency checks performed by `metaReviewReport`. */
+export const META_REVIEW_CHECKS = 6;
+/**
+ * Audit a ReviewReport for internal consistency.
+ *
+ * Checks (all deterministic, no I/O):
+ *  1. COUNT_MATCH: summary.totalFindings === findings.length
+ *  2. SEVERITY_SUM: summary severity buckets (critical+high+medium+low) total
+ *     to summary.totalFindings AND match the actual per-severity counts.
+ *  3. DIMENSION_SUM: summary.byDimension values sum to totalFindings and every
+ *     finding's dimension is present in report.dimensions.
+ *  4. SORT_ORDER: findings are severity-sorted (most severe first).
+ *  5. CONVERGENCE: findingsByRound sums to totalFindings and the `converged`
+ *     flag is consistent with the last round's new-finding count.
+ *  6. ROUND_SHAPE: every round has a positive round number; no round is
+ *     missing from the sequence. A round with zero findings is only flagged
+ *     when it is NOT the last round — an empty FINAL round means the review
+ *     converged (the last pass found nothing new), which is the expected,
+ *     successful termination of a dry-run, not a defect.
+ *
+ * Returns a MetaReviewResult; `passed` is true only when all checks pass.
+ */
+export function metaReviewReport(report) {
+    const issues = [];
+    const add = (code, severity, summary, detail) => {
+        issues.push({ code, severity, summary, detail });
+    };
+    // Guard: a null/undefined report is a hard failure, not a crash.
+    if (!report || typeof report !== 'object') {
+        return {
+            passed: false,
+            verdict: 'revise',
+            checksRun: META_REVIEW_CHECKS,
+            issues: [
+                {
+                    code: 'REPORT_UNDEFINED',
+                    severity: 'critical',
+                    summary: 'Report is missing or not an object',
+                    detail: 'metaReviewReport received no valid ReviewReport to audit.',
+                },
+            ],
+        };
+    }
+    const findings = Array.isArray(report.findings) ? report.findings : [];
+    const summary = report.summary ?? {};
+    const total = Number(summary.totalFindings ?? 0);
+    const dimensions = Array.isArray(report.dimensions) ? report.dimensions : [];
+    // 1. COUNT_MATCH
+    if (total !== findings.length) {
+        add('COUNT_MATCH', 'high', `summary.totalFindings (${total}) does not match findings.length (${findings.length})`, `The report claims ${total} findings but lists ${findings.length}.`);
+    }
+    // 2. SEVERITY_SUM
+    const sevCounts = { critical: 0, high: 0, medium: 0, low: 0 };
+    for (const f of findings) {
+        const s = f?.severity;
+        if (s && s in sevCounts)
+            sevCounts[s]++;
+    }
+    const bucketSum = sevCounts.critical + sevCounts.high + sevCounts.medium + sevCounts.low;
+    const declaredSeveritySum = Number(summary.critical ?? 0) +
+        Number(summary.high ?? 0) +
+        Number(summary.medium ?? 0) +
+        Number(summary.low ?? 0);
+    if (declaredSeveritySum !== total || bucketSum !== total) {
+        add('SEVERITY_SUM', 'high', 'Severity bucket counts are inconsistent with totalFindings', `declared buckets sum to ${declaredSeveritySum}, actual buckets sum to ${bucketSum}, ` +
+            `but totalFindings is ${total}.`);
+    }
+    // 3. DIMENSION_SUM
+    const byDim = summary.byDimension ?? {};
+    let dimSum = 0;
+    for (const v of Object.values(byDim))
+        dimSum += Number(v) || 0;
+    if (dimSum !== total) {
+        add('DIMENSION_SUM', 'high', 'byDimension counts do not sum to totalFindings', `byDimension sums to ${dimSum}, but totalFindings is ${total}.`);
+    }
+    const invalidDim = findings.find((f) => !dimensions.includes(f?.dimension));
+    if (invalidDim) {
+        add('DIMENSION_UNKNOWN', 'medium', `Finding references unknown dimension "${invalidDim.dimension}"`, `dimension "${invalidDim.dimension}" is not in report.dimensions ` +
+            `(${dimensions.join(', ') || 'none'}).`);
+    }
+    // 4. SORT_ORDER
+    const sorted = sortFindings(findings);
+    const isSorted = sorted.every((f, i) => f === findings[i]);
+    if (!isSorted) {
+        add('SORT_ORDER', 'low', 'Findings are not severity-sorted', 'findings should be ordered most-severe first (critical > high > medium > low).');
+    }
+    // 5. CONVERGENCE
+    const findingsByRound = Array.isArray(report.convergence?.findingsByRound)
+        ? report.convergence.findingsByRound
+        : [];
+    const convSum = findingsByRound.reduce((a, b) => a + Number(b) || 0, 0);
+    if (convSum !== total) {
+        add('CONVERGENCE_SUM', 'high', 'convergence.findingsByRound does not sum to totalFindings', `findingsByRound ${JSON.stringify(findingsByRound)} sums to ${convSum}, ` +
+            `but totalFindings is ${total}.`);
+    }
+    // `findingsByRound` is indexed by the actual round number (round r → index
+    // r-1), so the "last round" is the LAST RECORDED round's reported number, not
+    // the array's last index (the array is sized to the highest round, which only
+    // equals the record count for contiguous 1..N round numbers). Read the flag
+    // consistency the same way buildReviewReport/computeConvergence set it.
+    const reportRounds = Array.isArray(report.rounds) ? report.rounds : [];
+    const lastRecordedRound = reportRounds.length > 0 && typeof reportRounds[reportRounds.length - 1]?.round === 'number'
+        ? reportRounds[reportRounds.length - 1].round
+        : null;
+    const lastRoundNew = lastRecordedRound !== null && lastRecordedRound > 0
+        ? Number(findingsByRound[lastRecordedRound - 1] ?? 0)
+        : null;
+    const expectedConverged = lastRoundNew === 0;
+    if (report.convergence?.converged !== expectedConverged) {
+        add('CONVERGENCE_FLAG', 'medium', 'convergence.converged flag is inconsistent with the last round', `last round reported ${lastRoundNew} new findings, so converged should be ` +
+            `${expectedConverged}, but it is ${report.convergence?.converged}.`);
+    }
+    // 6. ROUND_SHAPE
+    const rounds = Array.isArray(report.rounds) ? report.rounds : [];
+    const seenRounds = new Set();
+    for (const [index, r] of rounds.entries()) {
+        if (!r || typeof r.round !== 'number' || r.round < 1) {
+            add('ROUND_NUMBER', 'medium', 'A round has a missing or non-positive round number', `round: ${JSON.stringify(r)}`);
+            continue;
+        }
+        seenRounds.add(r.round);
+        const isLastRound = index === rounds.length - 1;
+        if (!Array.isArray(r.findings) || (r.findings.length === 0 && !isLastRound)) {
+            add('ROUND_EMPTY', 'low', `Round ${r.round} has no findings`, 'A recorded round should contain at least one finding — except a final converged round, ' +
+                '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'}.`);
+        }
+    }
+    const passed = issues.length === 0;
+    return {
+        passed,
+        verdict: passed ? 'approved' : 'revise',
+        checksRun: META_REVIEW_CHECKS,
+        issues,
+    };
+}
+/**
+ * Build the final review report: pair the source report with its meta-review
+ * verdict and a rolled-up summary. Pure and deterministic.
+ */
+export function buildFinalReviewReport(report) {
+    const meta = metaReviewReport(report);
+    const summary = report?.summary ?? {};
+    const verdict = meta.passed ? 'approved' : 'needs_revision';
+    return {
+        verdict,
+        source: report,
+        metaReview: meta,
+        summary: {
+            totalFindings: Number(summary.totalFindings ?? 0),
+            critical: Number(summary.critical ?? 0),
+            high: Number(summary.high ?? 0),
+            medium: Number(summary.medium ?? 0),
+            low: Number(summary.low ?? 0),
+            converged: Boolean(report?.convergence?.converged),
+            totalRounds: Number(report?.convergence?.totalRounds ?? 0),
+            reportIssues: meta.issues.length,
+            verdict,
+        },
+    };
+}

package/dist/paths.js

@@ -0,0 +1,32 @@
+/**
+ * Shared filesystem layout for the iterate plugin's runtime state.
+ *
+ * All runtime artifacts live under `<projectRoot>/.iterate/`:
+ *   .iterate/decision-log.jsonl   — append-only decision log
+ *   .iterate/fixes/               — fix system: backups + fix registry
+ *   .iterate/checkpoint.json      — iteration checkpoint (resume support)
+ *
+ * Kept separate from config-loader so every tool points at the same dirs.
+ */
+import { join } from 'node:path';
+/** Runtime state root for a project (e.g. `<projectRoot>/.iterate`). */
+export function iterateDir(projectRoot) {
+    return join(projectRoot, '.iterate');
+}
+/** Fix-system directory (backups + registry). */
+export function fixesDir(projectRoot) {
+    return join(iterateDir(projectRoot), 'fixes');
+}
+/** Fix-registry file (JSON). */
+export function fixRegistryPath(projectRoot) {
+    return join(fixesDir(projectRoot), 'registry.json');
+}
+/** Fix-backup file for one fix id + timestamp. */
+export function fixBackupPath(projectRoot, id, timestamp) {
+    const safe = id.replace(/[^a-zA-Z0-9_-]/g, '_');
+    return join(fixesDir(projectRoot), `${safe}_${timestamp.replace(/[:.]/g, '-')}.bak`);
+}
+/** Iteration checkpoint file (JSON). */
+export function checkpointPath(projectRoot) {
+    return join(iterateDir(projectRoot), 'checkpoint.json');
+}