iterate-plugin 2.11.0 → 2.12.1

package/dist/skill-prompt.js

@@ -22,6 +22,7 @@ You have the iterate plugin installed, which registers these tools:
 - \`iterate_status\` — summarize the current run: mode, round, fixes applied, architectural remaining, decision-log size, checkpoint presence, and whether the run was interrupted (a checkpoint left on disk means the previous run was interrupted and can be resumed)
 - \`iterate_history\` — inspect the runtime state in detail: decision-log entries and applied fixes (optionally scoped to a round or a fixed file)
 - \`iterate_prune\` — remove stale runtime artifacts (\`.iterate/\` entries). Defaults to a read-only dry-run that reports what WOULD be removed; pass \`dryRun:false\` to actually prune.
+- \`iterate_transcript\` — runtime observatory file (\`.iterate/transcript.json\`). \`read\` fetches the persisted manifest including any steering \`nudge\` for this run's reviewers; \`capture\` (call once after the final report) persists the per-reviewer threads, convergence trend, findings, fixes, checkpoint, and timeline so the client observatory panel reflects the run; \`nudge\` sets/clears steering text the next round's reviewers read. Purely local, never touches source files.
 
 ### When to use
 When the user asks to review or iterate on the project (e.g. "review this project", "iterate on error handling", "check the codebase for issues", "dry-run review", "反复审查"), run an iterate **workflow** by calling the \`workflow\` tool.
@@ -77,6 +78,14 @@ const knownIntentional = (plan.knownIntentional || [])   // config personalizati
 let known = []              // cumulative DEDUPED findings fed back to reviewers
 const rounds = []           // raw per-round findings
 
+phase('transcript')
+// Read any steering nudge written (via iterate_transcript nudge) for this run's reviewers.
+const transRead = await agent(
+  'Call iterate_transcript({operation:"read"}) and return {nudge:<transcript.nudge ? transcript.nudge.text : null>}.',
+  Object.assign({ label: 'transcript:read' }, backend)
+)
+const steering = transRead && typeof transRead.nudge === 'string' && transRead.nudge ? transRead.nudge : null
+
 phase('review')
 for (let r = 1; r <= maxRounds; r++) {
   log('round ' + r + ' of ' + maxRounds + ' — finding NEW issues only')
@@ -98,6 +107,7 @@ for (let r = 1; r <= maxRounds; r++) {
         ? meta.reviewerPrompt
         : 'Review dimension "' + dim + '".'
       const extra =
+        (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (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.'
@@ -156,6 +166,13 @@ const metaRes = await agent(
 const finalReport = metaRes && metaRes.finalReport ? metaRes.finalReport : null
 const metaAudit = finalReport && finalReport.metaReview ? finalReport.metaReview : null
 
+// Persist the run's observatory transcript (reviewer threads, trend, findings)
+// so the client observatory panel reflects this review. Writes ONLY .iterate/transcript.json.
+await agent(
+  'Call iterate_transcript({operation:"capture", mode:"dry-run", goal:' + JSON.stringify(report.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + report.convergence.totalRounds + ', findingsByRound:' + JSON.stringify(report.convergence.findingsByRound || []) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+  Object.assign({ label: 'transcript:capture' }, backend)
+)
+
 return {
   mode: 'dry-run',
   goal: report.goal,
@@ -180,7 +197,7 @@ Key rules for dry-run:
 - Stop when a round reports 0 new findings (converged) or maxReviewRounds is reached.
 - The report (with per-round convergence stats + suggested fix priorities) is the deliverable.
 - **Meta-review**: after building the report, audit it with \`iterate_review({operation:"meta-review"})\` for internal consistency (counts, severity buckets, dimension sums, sort order, convergence math). The meta-review ALSO runs the hard code-evidence gate (default on): every finding's file/line is validated against real files on disk, so any fabricated location surfaces as a critical \`EVIDENCE_VIOLATION\` and flips the verdict to \`needs_revision\`. The \`finalReport.verdict\` is \`approved\` only when the report passes every check AND every finding anchors to real, read code; otherwise \`needs_revision\`. Surface the final report and its verdict as the closing deliverable.
-- Only a single \`report\` entry may be appended to the decision log; nothing else is written.
+- Only a single \`report\` entry may be appended to the decision log; nothing else is written to source files. The final \`iterate_transcript capture\` writes ONLY the observatory file (\`.iterate/transcript.json\`) so the client panel reflects the run — it is not a source-code write.
 
 ### Normal-mode workflow (autonomous closed loop)
 Set \`args.mode = "normal"\`. Loop: resume → plan → parallel review ×N → atomic fixes via \`iterate_fix\` → validate → rollback on failure → checkpoint → loop → auto-stop when zero findings remain.
@@ -238,6 +255,14 @@ let fixedCount = (checkpoint && typeof checkpoint.fixedCount === 'number') ? che
 let converged = false
 let abortedByValidation = false
 let failedCommands = []
+const fixRecords = []        // observatory fix records collected round by round
+
+// Read any steering nudge intended for this run's reviewers.
+const transRead = await agent(
+  'Call iterate_transcript({operation:"read"}) and return {nudge:<transcript.nudge ? transcript.nudge.text : null>}.',
+  Object.assign({ label: 'transcript:read' }, backend)
+)
+const steering = transRead && typeof transRead.nudge === 'string' && transRead.nudge ? transRead.nudge : null
 
 phase('loop')
 for (let r = startRound; r <= maxRounds; r++) {
@@ -264,6 +289,7 @@ for (let r = startRound; r <= maxRounds; r++) {
         ? meta.reviewerPrompt
         : 'Review dimension "' + dim + '" on the CURRENT code state (previous atomic findings are fixed).'
       const extra =
+        (steering ? '\\n STEERING — read this first: ' + steering : '') +
         (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))
@@ -308,12 +334,14 @@ for (let r = startRound; r <= maxRounds; r++) {
       'Apply the fixes for ' + file + ' using iterate_fix. For EACH finding in this list, ' +
       'read the current file, compute the edited full content (change <= ' + atomicMaxLines + ' lines), and call ' +
       'iterate_fix({ file: "' + file + '", content: <full new file content>, finding: <that finding>, round: ' + r + ' }). ' +
-      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff. ' +
-      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error} per iterate_fix call.',
+      'Apply the findings IN ORDER. After all fixes, call iterate_diff({ file: "' + file + '" }) to verify the accumulated diff and ' +
+      'read its line statistics (lines added/removed). ' +
+      'Findings: ' + JSON.stringify(byFile[file]) + '. Return the array of {id, ok, error, file, linesAdded, linesRemoved} per iterate_fix call ' +
+      '(id/ok required; put the file-wide line stats from iterate_diff on each record, or on the last record and 0 elsewhere).',
       Object.assign({ label: 'fix:' + file, phase: 'fix', schema: {
         type: 'object', additionalProperties: false,
         properties: {
-          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' } }, required: ['id', 'ok'] } }
+          fixes: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { id: { type: 'string' }, ok: { type: 'boolean' }, error: { type: 'string' }, file: { type: 'string' }, linesAdded: { type: 'integer' }, linesRemoved: { type: 'integer' } }, required: ['id', 'ok'] } }
         },
         required: ['fixes'] } }, backend)
     )))
@@ -321,6 +349,17 @@ for (let r = startRound; r <= maxRounds; r++) {
       if (res && Array.isArray(res.fixes)) {
         for (const fx of res.fixes) {
           if (fx && fx.ok === true) { fixedCount += 1; roundFixIds.push(fx.id) }
+          // Collect fix records for the observatory transcript (defensive defaults).
+          const fixFileKeys = Object.keys(byFile)
+          fixRecords.push({
+            id: fx && typeof fx.id === 'string' ? fx.id : '',
+            file: fx && typeof fx.file === 'string' ? fx.file : (fixFileKeys.length === 1 ? fixFileKeys[0] : ''),
+            round: r,
+            summary: '',
+            linesAdded: fx && typeof fx.linesAdded === 'number' ? fx.linesAdded : 0,
+            linesRemoved: fx && typeof fx.linesRemoved === 'number' ? fx.linesRemoved : 0,
+            success: !!(fx && fx.ok === true),
+          })
         }
       }
     }
@@ -403,6 +442,19 @@ if (!abortedByValidation) {
     { label: 'checkpoint:clear' }
   )
 }
+// Persist the run's observatory transcript (threads, trend, fixes, checkpoint)
+// so the client observatory panel reflects the run. Writes ONLY .iterate/transcript.json.
+const obsCheckpoint = abortedByValidation ? null : {
+  mode: 'normal',
+  round: rounds.length,
+  maxRounds: maxRounds,
+  fixedCount: fixedCount,
+  resumeCount: effectiveResumeCount,
+}
+await agent(
+  'Call iterate_transcript({operation:"capture", mode:"normal", goal:' + JSON.stringify(plan.goal) + ', maxRounds:' + maxRounds + ', roundsExecuted:' + rounds.length + ', findingsByRound:' + JSON.stringify(rounds.map(rr => (rr.findings && rr.findings.length) ? rr.findings.length : 0)) + ', fixes:' + JSON.stringify(fixRecords) + ', checkpoint:' + JSON.stringify(obsCheckpoint) + ', rounds:' + JSON.stringify(rounds.map(rr => ({ round: rr.round, findings: rr.findings, readFiles: rr.readFiles }))) + '}). Return {operation:"ok"}.',
+  { label: 'transcript:capture' }
+)
 return {
   mode: 'normal',
   goal: plan.goal,

package/dist/tools/transcript.js

@@ -0,0 +1,324 @@
+/**
+ * src/tools/transcript.ts — `iterate_transcript` tool.
+ *
+ * Exposes the runtime-observatory manifest to the model (and, via its persisted
+ * on-disk copy, to the client observatory panel). Purely local, deterministic,
+ * and safe:
+ *
+ *   - `read`     — return the persisted transcript manifest (or a structured
+ *                  "not found" empty view). Used each round by the workflow to
+ *                  pick up steering nudges, and polled by tool-reading agents.
+ *   - `capture`  — build a fresh transcript from the review `rounds` + `report`
+ *                  and persist it. Called by the canonical scripts after the
+ *                  final aggregate so the client always sees the latest run.
+ *   - `nudge`    — set (`text`) or clear (`text: null`) steering text persisted
+ *                  for the next round's reviewers to read.
+ *
+ * All writes are persisted to `.iterate/transcript.json` via an atomic
+ * tmp+rename so a crashed writer never leaves a corrupt manifest.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadEffectiveConfig, resolveProjectRootForExec, } from "../config-loader.js";
+import { transcriptPath } from "../paths.js";
+import { ReviewTranscriptBuilder } from "../transcript.js";
+import { readLive } from "../live.js";
+/** Build per-dimension threads for one round from its (dimension-tagged) findings. */
+function captureRound(builder, round) {
+    if (!round || typeof round !== 'object')
+        return;
+    const r = round;
+    const roundNo = typeof r.round === 'number' ? Math.floor(r.round) : 0;
+    if (roundNo <= 0)
+        return;
+    builder.roundStart(roundNo);
+    const findings = Array.isArray(r.findings) ? r.findings : [];
+    const readFiles = Array.isArray(r.readFiles) ? r.readFiles : [];
+    // Group the round's findings by dimension → one reviewer thread each.
+    const byDim = new Map();
+    for (const f of findings) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const rec = f;
+        const dim = typeof rec.dimension === 'string' && rec.dimension ? rec.dimension : 'review';
+        const list = byDim.get(dim) ?? [];
+        list.push(f);
+        byDim.set(dim, list);
+    }
+    if (byDim.size === 0) {
+        builder.reviewerSnapshot('review', [], readFiles);
+    }
+    else {
+        for (const [dim, list] of byDim)
+            builder.reviewerSnapshot(dim, list, readFiles);
+    }
+}
+/** Normalize the checkpoint shape if present. */
+function normalizeCheckpoint(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const c = input;
+    const round = typeof c.round === 'number' ? c.round : 0;
+    if (round <= 0)
+        return null;
+    return {
+        mode: c.mode === 'dry-run' || c.mode === 'normal' ? c.mode : 'normal',
+        round,
+        maxRounds: typeof c.maxRounds === 'number' ? c.maxRounds : 0,
+        fixedCount: typeof c.fixedCount === 'number' ? c.fixedCount : 0,
+        resumeCount: typeof c.resumeCount === 'number' ? c.resumeCount : 0,
+        updatedAt: typeof c.updatedAt === 'string' ? c.updatedAt : new Date().toISOString(),
+    };
+}
+/** Normalize a fix record. */
+function normalizeFix(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const f = input;
+    const id = typeof f.id === 'string' ? f.id : '';
+    const file = typeof f.file === 'string' ? f.file : '';
+    if (!id || !file)
+        return null;
+    return {
+        id,
+        timestamp: typeof f.timestamp === 'string' ? f.timestamp : new Date().toISOString(),
+        round: typeof f.round === 'number' ? f.round : 0,
+        file,
+        summary: typeof f.summary === 'string' ? f.summary : '',
+        linesAdded: typeof f.linesAdded === 'number' ? f.linesAdded : 0,
+        linesRemoved: typeof f.linesRemoved === 'number' ? f.linesRemoved : 0,
+        success: f.success !== false,
+    };
+}
+/** Register the `iterate_transcript` tool. */
+export function registerTranscriptTool(ctx) {
+    ctx.tools.register(defineTool({
+        name: 'iterate_transcript',
+        description: 'Runtime-observatory transcript for the iterate workflow. ' +
+            '`read` returns the current persisted transcript manifest (per-reviewer threads, ' +
+            'convergence series, findings, fixes, checkpoint, timeline, and any steering nudge ' +
+            'written for the next round). ' +
+            '`capture` builds a fresh transcript from the review `rounds` + `report` and persists it ' +
+            '(call once after the final aggregate so the UI reflects the run). ' +
+            '`nudge` sets (text) or clears (text:null) steering text the next round\'s reviewers read. ' +
+            'Purely local and deterministic — never touches source files.',
+        parameters: {
+            operation: {
+                type: 'string',
+                required: true,
+                description: '"read" to fetch the manifest, "capture" to persist one, "nudge" to set steering text.',
+                enum: ['read', 'capture', 'nudge'],
+            },
+            rounds: {
+                type: 'json',
+                description: 'For `capture`: per-round findings, each [{round, findings:[{dimension,file,line?,severity,summary,…}], readFiles:[…]}].',
+            },
+            report: {
+                type: 'json',
+                description: 'For `capture`: the ReviewReport (convergence.findingsByRound used for the trend).',
+            },
+            mode: {
+                type: 'string',
+                description: 'For `capture`: run mode ("dry-run" | "normal"). Default dry-run.',
+                enum: ['dry-run', 'normal'],
+            },
+            goal: { type: 'string', description: 'For `capture`: run goal.' },
+            maxRounds: { type: 'integer', description: 'For `capture`: round cap.' },
+            roundsExecuted: { type: 'integer', description: 'For `capture`: number of rounds actually executed.' },
+            findingsByRound: { type: 'json', description: 'For `capture`: the per-round new-findings count series (report.convergence.findingsByRound). Preferred over passing the whole report.' },
+            checkpoint: { type: 'json', description: 'For `capture`: checkpoint summary (optional).' },
+            fixes: {
+                type: 'json',
+                description: 'For `capture`: array of applied fixes [{id, file, round, summary, linesAdded, linesRemoved, success}].',
+            },
+            refReadFiles: { type: 'json', description: 'For `capture`: flat array of all read files across rounds (optional).' },
+            text: { type: 'string', description: 'For `nudge`: steering text to set (or null to clear).' },
+            path: { type: 'string', description: 'Project root directory (default: current working directory).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    operation: { type: 'string', required: true },
+                    found: { type: 'boolean' },
+                    transcript: { type: 'json' },
+                    live: { type: 'json', description: 'Recent live reviewer-activity entries (newest first).' },
+                    updated: { type: 'boolean' },
+                    error: { type: 'string' },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+        },
+        async execute(args, exec) {
+            const resolved = resolveProjectRootForExec(exec, args.path);
+            if (!resolved.ok)
+                return { operation: args.operation, error: resolved.reason };
+            const projectRoot = resolved.root;
+            const file = transcriptPath(projectRoot);
+            const { config } = loadEffectiveConfig(projectRoot);
+            const approval = config.observatory?.approval ?? 'ask';
+            if (args.operation === 'read') {
+                const live = await readLive(projectRoot);
+                if (!existsSync(file)) {
+                    return {
+                        operation: 'read',
+                        found: false,
+                        live: live,
+                        transcript: new ReviewTranscriptBuilder({
+                            project: projectRoot,
+                            approval,
+                        }).serialize(),
+                    };
+                }
+                try {
+                    const raw = await readFile(file, 'utf-8');
+                    const parsed = JSON.parse(raw);
+                    return {
+                        operation: 'read',
+                        found: true,
+                        live: live,
+                        transcript: parsed,
+                    };
+                }
+                catch (err) {
+                    return {
+                        operation: 'read',
+                        found: false,
+                        error: `Failed to read transcript: ${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+            }
+            if (args.operation === 'nudge') {
+                let manifest = null;
+                if (existsSync(file)) {
+                    try {
+                        const parsed = JSON.parse(await readFile(file, 'utf-8'));
+                        manifest = parsed;
+                    }
+                    catch {
+                        manifest = null;
+                    }
+                }
+                const builder = manifest
+                    ? rehydrateBuilder(manifest, approval)
+                    : new ReviewTranscriptBuilder({ project: projectRoot, mode: 'normal', approval });
+                builder.setNudge(typeof args.text === 'string' && args.text.trim() ? args.text : null);
+                await persist(file, builder.serialize());
+                return {
+                    operation: 'nudge',
+                    updated: true,
+                    transcript: builder.serialize(),
+                };
+            }
+            // capture
+            const mode = args.mode === 'normal' ? 'normal' : 'dry-run';
+            const goal = typeof args.goal === 'string' ? args.goal : '';
+            const maxRounds = typeof args.maxRounds === 'number' ? Math.floor(args.maxRounds) : 0;
+            const builder = new ReviewTranscriptBuilder({ project: projectRoot, mode, approval, goal, maxRounds });
+            const report = args.report;
+            const reportFindings = report && typeof report === 'object' && Array.isArray(report.findings)
+                ? report.findings
+                : [];
+            const convergence = Array.isArray(args.findingsByRound) ? args.findingsByRound
+                : report && typeof report === 'object' && report.convergence
+                    ? report.convergence.findingsByRound ?? []
+                    : [];
+            const rounds = Array.isArray(args.rounds) ? args.rounds : [];
+            for (const r of rounds)
+                captureRound(builder, r);
+            if (rounds.length === 0) {
+                // No pre-grouped rounds: fall back to the report's flattened findings.
+                const readFiles = Array.isArray(args.refReadFiles) ? args.refReadFiles : [];
+                const byDim = new Map();
+                for (const f of reportFindings) {
+                    if (!f || typeof f !== 'object')
+                        continue;
+                    const rec = f;
+                    const dim = typeof rec.dimension === 'string' && rec.dimension ? rec.dimension : 'review';
+                    const list = byDim.get(dim) ?? [];
+                    list.push(f);
+                    byDim.set(dim, list);
+                }
+                for (const [dim, list] of byDim)
+                    builder.reviewerSnapshot(dim, list, readFiles);
+            }
+            // Convergence series from the report (position per round).
+            for (let i = 0; i < convergence.length; i += 1) {
+                const n = convergence[i];
+                if (typeof n === 'number')
+                    builder.snapshotConvergence(i + 1, n);
+            }
+            const roundsExecuted = typeof args.roundsExecuted === 'number' ? Math.floor(args.roundsExecuted) : rounds.length;
+            if (roundsExecuted > 0)
+                builder.roundStart(roundsExecuted, maxRounds);
+            builder.recordCheckpoint(normalizeCheckpoint(args.checkpoint));
+            if (Array.isArray(args.fixes)) {
+                for (const fx of args.fixes) {
+                    const record = normalizeFix(fx);
+                    if (record)
+                        builder.fix(record);
+                }
+            }
+            // Convergence "found nothing → settled" marker when the trend ends on 0.
+            const last = convergence[convergence.length - 1];
+            if (convergence.length > 0 && last === 0)
+                builder.finish();
+            await persist(file, builder.serialize());
+            const live = await readLive(projectRoot);
+            return {
+                operation: 'capture',
+                found: true,
+                updated: true,
+                live: live,
+                transcript: builder.serialize(),
+            };
+        },
+    }));
+}
+/** Rebuild a builder from a persisted manifest so nudge edits preserve history. */
+function rehydrateBuilder(manifest, approval) {
+    const builder = new ReviewTranscriptBuilder({
+        project: manifest.project,
+        mode: manifest.mode ?? null,
+        approval,
+        goal: manifest.goal,
+        maxRounds: manifest.maxRounds,
+    });
+    for (const r of Array.isArray(manifest.rounds) ? manifest.rounds : []) {
+        builder.roundStart(r.round, manifest.maxRounds);
+        for (const t of Array.isArray(r.threads) ? r.threads : []) {
+            builder.reviewerStart(t.dimension || 'review', t.attempt || 1);
+            builder.reviewerMessage((t.messages ?? []).join('\n'));
+            builder.reviewerRead(t.readFiles ?? []);
+            for (const f of t.findings ?? [])
+                builder.reviewerFindings([f]);
+        }
+    }
+    for (let idx = 0; idx < (manifest.convergence ?? []).length; idx += 1) {
+        const n = manifest.convergence[idx];
+        if (typeof n === 'number' && n >= 0)
+            builder.snapshotConvergence(idx + 1, n);
+    }
+    if (manifest.checkpoint)
+        builder.recordCheckpoint(manifest.checkpoint);
+    if (Array.isArray(manifest.fixes))
+        for (const fx of manifest.fixes)
+            builder.fix(fx);
+    if (Array.isArray(manifest.timeline))
+        for (const e of manifest.timeline)
+            builder.decision(e);
+    builder.setNudge(manifest.nudge?.text ?? null);
+    if (!manifest.active)
+        builder.finish();
+    return builder;
+}
+/** Atomically persist a manifest (tmp + rename) under `.iterate/`. */
+async function persist(file, manifest) {
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, JSON.stringify(manifest, null, 2), 'utf-8');
+    await rename(tmp, file);
+}