review-workspace 1.4.0 → 1.6.0

package/dist/bundle/carry-forward.js

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parsePatch } from "../patch/parse.js";
+import { carryForwardComment, readQuestions } from "../questions/questions-log.js";
+import { evaluateResolution } from "./resolution.js";
+import { incrementalTouchedPaths } from "./incremental-patch.js";
+export function createCaches() {
+    return { chain: new Map(), patch: new Map(), reviewDocument: new Map() };
+}
+export function readChain(bundlePath, caches = createCaches()) {
+    if (!caches.chain.has(bundlePath)) {
+        const path = join(bundlePath, 'chain.json');
+        caches.chain.set(bundlePath, existsSync(path) ? JSON.parse(readFileSync(path, 'utf-8')) : undefined);
+    }
+    return caches.chain.get(bundlePath);
+}
+export function resolvePreviousBundlePath(bundlePath, chain) {
+    return resolve(bundlePath, chain.previousBundle);
+}
+function readPatch(bundlePath, caches) {
+    if (!caches.patch.has(bundlePath)) {
+        caches.patch.set(bundlePath, parsePatch(readFileSync(join(bundlePath, 'changes.diff'), 'utf-8')));
+    }
+    return caches.patch.get(bundlePath);
+}
+function readReviewDocument(bundlePath, caches) {
+    if (!caches.reviewDocument.has(bundlePath)) {
+        caches.reviewDocument.set(bundlePath, JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8')));
+    }
+    return caches.reviewDocument.get(bundlePath);
+}
+function openChangeRequests(bundlePath) {
+    return readQuestions(bundlePath).filter((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+}
+/**
+ * Shared shape behind every chain-walking function below: a round-1 bundle (no
+ * `chain.json`) is the base case, otherwise resolve the previous round's bundle path
+ * and hand it (plus the chain itself, for its `round` number) to `step`.
+ */
+function walkChain(bundlePath, caches, base, step) {
+    const chain = readChain(bundlePath, caches);
+    return chain ? step(resolvePreviousBundlePath(bundlePath, chain), chain) : base();
+}
+/**
+ * Copies every still-open change-request Comment from the previous round in the chain
+ * into this round's own comment log, so it's visible and actionable here too. Idempotent
+ * — safe to call every time a round-N bundle is opened, validated, or rendered.
+ * No-ops for a round-1 bundle (no `chain.json`).
+ */
+export function carryForwardChain(bundlePath, caches = createCaches()) {
+    walkChain(bundlePath, caches, () => undefined, (previousBundlePath) => {
+        for (const comment of openChangeRequests(previousBundlePath)) {
+            carryForwardComment(bundlePath, comment);
+        }
+    });
+}
+/**
+ * Evaluates every comment carried forward from the previous round against this round's
+ * incremental patch. Assumes `carryForwardChain` has already copied them into this
+ * round's own log — this only reads, never writes.
+ */
+export function computeCarriedResolutions(bundlePath, caches = createCaches()) {
+    return walkChain(bundlePath, caches, () => [], (previousBundlePath) => {
+        const carriedIds = new Set(openChangeRequests(previousBundlePath).map((c) => c.id));
+        if (carriedIds.size === 0)
+            return [];
+        const previousPatch = readPatch(previousBundlePath, caches);
+        const currentPatch = readPatch(bundlePath, caches);
+        return readQuestions(bundlePath)
+            .filter((c) => carriedIds.has(c.id))
+            .map((comment) => ({ comment, resolution: evaluateResolution(comment, previousPatch, currentPatch) }));
+    });
+}
+function findOriginRound(bundlePath, commentId, caches) {
+    return walkChain(bundlePath, caches, () => 1, (previousBundlePath, chain) => {
+        const inPreviousRound = readQuestions(previousBundlePath).some((c) => c.id === commentId);
+        return inPreviousRound ? findOriginRound(previousBundlePath, commentId, caches) : chain.round;
+    });
+}
+/**
+ * The full comment history for this bundle: its own log, plus every ancestor round's
+ * comments not already present here (own log id, e.g. a resolved-in-round-1 change
+ * request never carried forward as open). Resolved comments are never dropped — they
+ * simply keep showing from whichever round's log actually holds them (framework.md's
+ * "never silently discard evidence").
+ */
+export function collectCommentHistory(bundlePath, caches = createCaches()) {
+    const own = readQuestions(bundlePath).map((c) => ({ ...c, originRound: findOriginRound(bundlePath, c.id, caches) }));
+    return walkChain(bundlePath, caches, () => own, (previousBundlePath) => {
+        const ownIds = new Set(own.map((c) => c.id));
+        const ancestorHistory = collectCommentHistory(previousBundlePath, caches).filter((c) => !ownIds.has(c.id));
+        return [...own, ...ancestorHistory].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    });
+}
+/** Every Comment relevant to this bundle, with its claimed Resolution attached where one applies. */
+export function listComments(bundlePath, caches = createCaches()) {
+    const resolutions = new Map(computeCarriedResolutions(bundlePath, caches).map((c) => [c.comment.id, c.resolution]));
+    return collectCommentHistory(bundlePath, caches).map((comment) => ({ ...comment, resolution: resolutions.get(comment.id) }));
+}
+function targetKey(target) {
+    switch (target.type) {
+        case 'file':
+            return `file:${target.path}`;
+        case 'binary':
+            return `binary:${target.path}`;
+        case 'hunk':
+            return `hunk:${target.path}:${target.hunkIndex}`;
+        case 'line':
+            return `line:${target.path}:${target.side}:${target.line}`;
+    }
+}
+/**
+ * Behavioral Groups/Annotations carried forward from earlier rounds for material the
+ * incremental patch doesn't touch — the round-N Generator is only expected to write
+ * fresh ones for genuinely new material (framework.md's "slim rounds"). Recurses the
+ * whole chain so a group/annotation keeps surfacing across every later round until a
+ * round's incremental patch actually touches its file, or a later round redeclares it.
+ */
+export function collectCarriedReviewContent(bundlePath, ownDocument, caches = createCaches()) {
+    return walkChain(bundlePath, caches, () => ({ behavioralGroups: [], annotations: [] }), (previousBundlePath) => {
+        const previousDocument = readReviewDocument(previousBundlePath, caches);
+        const previousCarried = collectCarriedReviewContent(previousBundlePath, previousDocument, caches);
+        const previousAll = {
+            behavioralGroups: [...(previousDocument.behavioralGroups ?? []), ...previousCarried.behavioralGroups],
+            annotations: [...(previousDocument.annotations ?? []), ...previousCarried.annotations],
+        };
+        const touchedPaths = incrementalTouchedPaths(readPatch(previousBundlePath, caches), readPatch(bundlePath, caches));
+        const ownTargetKeys = new Set((ownDocument.annotations ?? []).map((a) => targetKey(a.target)));
+        const ownGroupIds = new Set((ownDocument.behavioralGroups ?? []).map((g) => g.id));
+        return {
+            annotations: previousAll.annotations.filter((a) => !touchedPaths.has(a.target.path) && !ownTargetKeys.has(targetKey(a.target))),
+            behavioralGroups: previousAll.behavioralGroups.filter((g) => !ownGroupIds.has(g.id) && !(g.targets ?? []).some((t) => touchedPaths.has(t.path))),
+        };
+    });
+}

package/dist/bundle/incremental-patch.js

@@ -0,0 +1,35 @@
+/**
+ * Both a round's own `changes.diff` and its predecessor's are full base..head patches
+ * (ADR 0002 — every bundle is a real Comparison), so there is no git access to compute
+ * `previousHead..head` directly (see framework.md's product boundary). Instead, a hunk
+ * that appears verbatim in both is treated as unchanged since the previous round; one
+ * that doesn't is incremental. This slightly over-reports "touched" when unrelated
+ * earlier edits shift a hunk's line numbers without changing its content, which is the
+ * conservative direction (never silently treats real change as untouched).
+ */
+function hunkFingerprint(path, hunkIndex, hunk) {
+    return JSON.stringify([path, hunkIndex, hunk]);
+}
+/** Hunks in `currentPatch`'s file at `path` that weren't present, verbatim and at the same
+ * index, in `previousPatch`. A file absent from `previousPatch` counts as entirely incremental.
+ * The index is part of the fingerprint so two textually-identical hunks at different
+ * locations (e.g. near-duplicate boilerplate) can never be mistaken for each other. */
+export function incrementalHunks(previousPatch, currentPatch, path) {
+    const currentFile = currentPatch.files.find((f) => f.path === path);
+    if (!currentFile)
+        return [];
+    const previousFile = previousPatch.files.find((f) => f.path === path);
+    if (!previousFile)
+        return currentFile.hunks;
+    const previousHunkKeys = new Set(previousFile.hunks.map((hunk, index) => hunkFingerprint(path, index, hunk)));
+    return currentFile.hunks.filter((hunk, index) => !previousHunkKeys.has(hunkFingerprint(path, index, hunk)));
+}
+/** File paths in `currentPatch` with at least one hunk incremental since `previousPatch`. */
+export function incrementalTouchedPaths(previousPatch, currentPatch) {
+    const touched = new Set();
+    for (const file of currentPatch.files) {
+        if (incrementalHunks(previousPatch, currentPatch, file.path).length > 0)
+            touched.add(file.path);
+    }
+    return touched;
+}

package/dist/bundle/publish-with-handoff.js

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { exportHandoff } from "../handoff/export-handoff.js";
+import { readQuestions } from "../questions/questions-log.js";
+import { DEFAULT_LIMITS } from "../security/limits.js";
+import { publishBundle } from "./publish.js";
+import { readChain } from "./round.js";
+/**
+ * Publishes a bundle and, only once the publish itself succeeds, exports its
+ * open change-request Comments as a hand-off file into the target repo's
+ * working tree. The round number comes from `chain.json` when present
+ * (round N>1), otherwise round 1 — independent of chaining, same as the
+ * hand-off export itself.
+ */
+export async function publishBundleAndExportHandoff(bundlePath, options) {
+    const result = publishBundle(bundlePath, options.limits ?? DEFAULT_LIMITS);
+    if (!result.ok)
+        return result;
+    const document = JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8'));
+    const round = readChain(bundlePath)?.round ?? 1;
+    const handoff = await exportHandoff({
+        bundlePath,
+        comparison: document.comparison,
+        round,
+        comments: readQuestions(bundlePath),
+        annotations: document.annotations ?? [],
+        ask: options.ask,
+        repoPathCachePath: options.repoPathCachePath,
+    });
+    return { ...result, handoff };
+}

package/dist/bundle/resolution.js

@@ -0,0 +1,68 @@
+import { resolveTarget } from "./resolve-diagnostics.js";
+import { incrementalHunks } from "./incremental-patch.js";
+function targetHunkIndex(target, patch) {
+    const file = patch.files.find((f) => f.path === target.path);
+    if (!file)
+        return undefined;
+    if (target.type === 'hunk')
+        return target.hunkIndex;
+    if (target.type !== 'line')
+        return undefined;
+    return file.hunks.findIndex((h) => h.lines.some((l) => (target.side === 'base' ? l.oldLine === target.line : l.newLine === target.line)));
+}
+/**
+ * Evaluates one carried-forward change-request Comment against the round's incremental
+ * patch. `target-gone` reuses the same Target-resolution logic the engine already uses
+ * to flag stale Targets in `resolve-diagnostics.ts`, rather than reinventing it.
+ */
+export function evaluateResolution(comment, previousPatch, currentPatch) {
+    const target = comment.target;
+    if (!target) {
+        const anyIncrementalChange = currentPatch.files.some((f) => incrementalHunks(previousPatch, currentPatch, f.path).length > 0);
+        return anyIncrementalChange
+            ? {
+                commentId: comment.id,
+                status: 'target-partially-touched',
+                evidence: 'The incremental patch changed other content, but this comment has no Target to correlate against.',
+            }
+            : { commentId: comment.id, status: 'target-untouched', evidence: 'No incremental changes were made in this round.' };
+    }
+    const staleDiagnostic = resolveTarget(target, currentPatch);
+    if (staleDiagnostic) {
+        const detail = 'detail' in staleDiagnostic ? staleDiagnostic.detail : 'the Target no longer resolves';
+        return {
+            commentId: comment.id,
+            status: 'target-gone',
+            evidence: `The comment's original Target no longer resolves against this round's patch: ${detail}`,
+        };
+    }
+    const touchedHunks = incrementalHunks(previousPatch, currentPatch, target.path);
+    if (touchedHunks.length === 0) {
+        return {
+            commentId: comment.id,
+            status: 'target-untouched',
+            evidence: `${target.path} has no incremental changes since the previous round.`,
+        };
+    }
+    if (target.type === 'file' || target.type === 'binary') {
+        return {
+            commentId: comment.id,
+            status: 'target-partially-touched',
+            evidence: `${touchedHunks.length} hunk(s) changed in ${target.path} since the previous round.`,
+        };
+    }
+    const currentFile = currentPatch.files.find((f) => f.path === target.path);
+    const hunkIndex = targetHunkIndex(target, currentPatch);
+    const targetedHunkChanged = hunkIndex !== undefined && hunkIndex >= 0 && touchedHunks.includes(currentFile.hunks[hunkIndex]);
+    return targetedHunkChanged
+        ? {
+            commentId: comment.id,
+            status: 'target-touched',
+            evidence: `The hunk containing this comment's Target changed in the incremental patch — this is a mechanical signal only, not a judgment that the underlying concern was actually addressed.`,
+        }
+        : {
+            commentId: comment.id,
+            status: 'target-partially-touched',
+            evidence: `${target.path} changed elsewhere in the incremental patch, but not at this comment's exact Target.`,
+        };
+}

package/dist/bundle/resolve-diagnostics.js

@@ -22,7 +22,8 @@ function checkAssetPath(bundlePath, assetPath, limits) {
     }
     return undefined;
 }
-function resolveTarget(target, patch) {
+/** Resolves a Target against a patch, returning the Diagnostic that explains why it's unresolved/stale, or undefined when it resolves cleanly. */
+export function resolveTarget(target, patch) {
     const file = findFile(patch, target.path);
     if (target.type === 'file') {
         if (!file)

package/dist/bundle/round.js

@@ -13,6 +13,13 @@ export function mrKeyFor(comparison) {
 function readReviewDocument(bundlePath) {
     return JSON.parse(readFileSync(join(bundlePath, 'review.json'), 'utf-8'));
 }
+/** Reads a bundle's `chain.json`, if it has one — absent for every round-1 bundle. */
+export function readChain(bundlePath) {
+    const path = join(bundlePath, 'chain.json');
+    if (!existsSync(path))
+        return undefined;
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
 /**
  * Reads a bundle directory name shaped like `<name>-r{N}` and splits it into
  * the chain's base name and that bundle's round number. A name with no

package/dist/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { readFileSync } from 'node:fs';
 import { validateBundle } from "./bundle/validate-bundle.js";
-import { publishBundle } from "./bundle/publish.js";
+import { publishBundleAndExportHandoff } from "./bundle/publish-with-handoff.js";
 import { checkRound, scaffoldNextRound } from "./bundle/round.js";
+import { askForRepoPathOnStdin } from "./handoff/ask-repo-path.js";
+import { carryForwardChain } from "./bundle/carry-forward.js";
 import { startReviewServer } from "./server/create-server.js";
 const [, , command, bundlePath, ...rest] = process.argv;
 function fail(message) {
@@ -17,6 +19,7 @@ if (!command || !bundlePath) {
     fail('Usage: review-workspace <open|publish|serve|round> <bundlePath> [--port N] [--live-head SHA --patch FILE]');
 }
 if (command === 'open') {
+    carryForwardChain(bundlePath);
     const result = validateBundle(bundlePath);
     if (!result.valid) {
         fail(`Cannot open bundle: ${result.blockingReason} — ${result.message}`);
@@ -27,11 +30,14 @@ if (command === 'open') {
     }
 }
 else if (command === 'publish') {
-    const result = publishBundle(bundlePath);
+    const result = await publishBundleAndExportHandoff(bundlePath, { ask: askForRepoPathOnStdin });
     if (!result.ok) {
         fail(`Publish rejected: ${result.blockingReason} — ${result.message}`);
     }
     console.log('Published.');
+    if (result.handoff?.written) {
+        console.log(`Hand-off file written: ${result.handoff.filePath}`);
+    }
 }
 else if (command === 'round') {
     const liveHead = flagValue('--live-head');

package/dist/handoff/ask-repo-path.js

@@ -0,0 +1,17 @@
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+/**
+ * Real interactive `AskForRepoPath` implementation for CLI/server use —
+ * prompts on stdin/stdout. Kept separate from `repo-path-cache.ts` so that
+ * module stays free of any actual I/O and easy to unit test with a stub `ask`.
+ */
+export async function askForRepoPathOnStdin(repoSlug) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await rl.question(`Local checkout path for ${repoSlug}: `);
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/handoff/build-handoff-markdown.js

@@ -0,0 +1,110 @@
+import { resolve } from 'node:path';
+const GENERAL_GROUP = '(general — no Target)';
+function targetPath(target) {
+    return target.path;
+}
+function targetKey(target) {
+    switch (target.type) {
+        case 'file':
+            return `file:${target.path}`;
+        case 'binary':
+            return `binary:${target.path}`;
+        case 'hunk':
+            return `hunk:${target.path}:${target.hunkIndex}`;
+        case 'line':
+            return `line:${target.path}:${target.side}:${target.line}`;
+    }
+}
+// Same-type-same-Target only: a file-level comment does not pick up
+// hunk-level Annotations on that file (or vice versa). Cross-granularity
+// matching is a coarser question ("does this Annotation touch material this
+// comment also concerns?") that issue #10 doesn't ask for — it wants the
+// Annotation the comment was raised against, i.e. the same Target.
+function targetsEqual(a, b) {
+    return targetKey(a) === targetKey(b);
+}
+function describeTarget(target) {
+    switch (target.type) {
+        case 'file':
+            return `File: ${target.path}`;
+        case 'hunk':
+            return `Hunk #${target.hunkIndex} in ${target.path}`;
+        case 'line':
+            return `Line ${target.line} (${target.side}) in ${target.path}`;
+        case 'binary':
+            return `Binary change: ${target.path}`;
+    }
+}
+function openChangeRequests(comments) {
+    return comments.filter((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+}
+function groupByFile(comments) {
+    const byFile = new Map();
+    for (const comment of comments) {
+        const key = comment.target ? targetPath(comment.target) : GENERAL_GROUP;
+        const group = byFile.get(key) ?? [];
+        group.push(comment);
+        byFile.set(key, group);
+    }
+    return byFile;
+}
+function orderedFileKeys(byFile) {
+    return [...byFile.keys()].sort((a, b) => {
+        if (a === GENERAL_GROUP)
+            return 1;
+        if (b === GENERAL_GROUP)
+            return -1;
+        return a.localeCompare(b);
+    });
+}
+function metadataBlock(input) {
+    return [
+        '<!--',
+        'review-workspace-handoff',
+        `bundlePath: ${resolve(input.bundlePath)}`,
+        `repository: ${input.comparison.repository ?? ''}`,
+        `mrNumber: ${input.comparison.number ?? ''}`,
+        `round: ${input.round}`,
+        '-->',
+    ];
+}
+/**
+ * Builds the hand-off Markdown a separate implementer-side skill parses.
+ * Content is raw: every open change-request Comment verbatim, grouped by
+ * file, with its exact Target and any Annotation raised against that same
+ * Target for context. This exact shape is a parsed contract — golden-tested,
+ * do not reformat without updating that consumer too.
+ */
+export function buildHandoffMarkdown(input) {
+    const comments = openChangeRequests(input.comments);
+    const lines = [`# Change requests — round ${input.round}`, '', ...metadataBlock(input), ''];
+    if (comments.length === 0) {
+        lines.push('_No open change-request comments._');
+        return lines.join('\n') + '\n';
+    }
+    const byFile = groupByFile(comments);
+    for (const file of orderedFileKeys(byFile)) {
+        lines.push(`## ${file}`);
+        lines.push('');
+        const fileComments = [...(byFile.get(file) ?? [])].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+        for (const comment of fileComments) {
+            lines.push(comment.target ? `### ${describeTarget(comment.target)}` : '### (no Target)');
+            if (comment.target?.type === 'line') {
+                lines.push(`> ${comment.target.expectedText}`);
+            }
+            lines.push('');
+            lines.push(comment.body);
+            lines.push('');
+            const relatedAnnotations = comment.target
+                ? input.annotations.filter((a) => targetsEqual(a.target, comment.target))
+                : [];
+            for (const annotation of relatedAnnotations) {
+                lines.push(`**Annotation (${annotation.kind ?? 'note'}):** ${annotation.summary}`);
+                lines.push('');
+            }
+            lines.push('---');
+            lines.push('');
+        }
+    }
+    return lines.join('\n').replace(/\n{2,}$/, '\n');
+}

package/dist/handoff/ensure-gitignore.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const ENTRY = '.review-feedback/';
+const COVERING_PATTERNS = new Set(['.review-feedback/', '.review-feedback', '.review-feedback/**', '.review-feedback/*']);
+function lineCoversHandoffDir(line) {
+    return COVERING_PATTERNS.has(line.trim());
+}
+/**
+ * Ensures the target repo's `.gitignore` excludes `.review-feedback/` —
+ * creating the file if it doesn't exist, appending the entry if the file
+ * exists but neither an exact nor a broader matching entry already covers it.
+ */
+export function ensureGitignoreExcludesHandoff(repoPath) {
+    const gitignorePath = join(repoPath, '.gitignore');
+    if (!existsSync(gitignorePath)) {
+        writeFileSync(gitignorePath, `${ENTRY}\n`);
+        return;
+    }
+    const content = readFileSync(gitignorePath, 'utf-8');
+    if (content.split('\n').some(lineCoversHandoffDir))
+        return;
+    const withTrailingNewline = content.endsWith('\n') ? content : `${content}\n`;
+    writeFileSync(gitignorePath, `${withTrailingNewline}${ENTRY}\n`);
+}

package/dist/handoff/export-handoff.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildHandoffMarkdown } from "./build-handoff-markdown.js";
+import { ensureGitignoreExcludesHandoff } from "./ensure-gitignore.js";
+import { DEFAULT_REPO_PATH_CACHE_PATH, resolveRepoPath } from "./repo-path-cache.js";
+/**
+ * Exports open change-request Comments as a self-describing hand-off
+ * Markdown file into the target repo's local working tree, and ensures
+ * `.review-feedback/` is gitignored there. A no-op when there are no open
+ * change-requests — this is what makes it safe to call after every publish.
+ */
+export async function exportHandoff(options) {
+    const { bundlePath, comparison, round, comments, annotations, ask, repoPathCachePath } = options;
+    const hasOpenChangeRequest = comments.some((c) => c.kind === 'change-request' && c.status === 'open' && !c.resolved);
+    if (!hasOpenChangeRequest)
+        return { written: false };
+    if (!comparison.repository) {
+        throw new Error('comparison.repository is required to export a hand-off file');
+    }
+    const repoPath = await resolveRepoPath(comparison.repository, ask, repoPathCachePath ?? DEFAULT_REPO_PATH_CACHE_PATH);
+    const markdown = buildHandoffMarkdown({ bundlePath, comparison, round, comments, annotations });
+    const feedbackDir = join(repoPath, '.review-feedback');
+    mkdirSync(feedbackDir, { recursive: true });
+    const filePath = join(feedbackDir, `${comparison.number}-round${round}.md`);
+    writeFileSync(filePath, markdown);
+    ensureGitignoreExcludesHandoff(repoPath);
+    return { written: true, filePath, repoPath };
+}

package/dist/handoff/repo-path-cache.js

@@ -0,0 +1,28 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+export const DEFAULT_REPO_PATH_CACHE_PATH = join(homedir(), '.claude', 'review-workspace-repo-paths.json');
+function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return {};
+    return JSON.parse(readFileSync(cachePath, 'utf-8'));
+}
+function writeCache(cachePath, cache) {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify(cache, null, 2) + '\n');
+}
+/**
+ * Resolves a target repo's local checkout path for `repoSlug`. Reuses a
+ * cached answer as long as it still exists on disk; asks (via `ask`) and
+ * caches the answer otherwise — this covers both "never asked before" and
+ * "the cached checkout was moved or deleted" in the same branch.
+ */
+export async function resolveRepoPath(repoSlug, ask, cachePath = DEFAULT_REPO_PATH_CACHE_PATH) {
+    const cache = readCache(cachePath);
+    const cached = cache[repoSlug];
+    if (cached && existsSync(cached))
+        return cached;
+    const answer = await ask(repoSlug);
+    writeCache(cachePath, { ...cache, [repoSlug]: answer });
+    return answer;
+}

package/dist/questions/questions-log.js

@@ -105,6 +105,25 @@ export function resolveComment(bundlePath, commentId) {
         comment: { ...comment, resolved: true, resolvedAt: entry.createdAt },
     };
 }
+/**
+ * Copies a still-open change-request Comment from an earlier round's log into this
+ * round's own log, preserving its id and original createdAt so a Reviewer can act on it
+ * (resolve it) directly from this round. No-ops if this round's log already has a
+ * `raised` entry for that id — safe to call on every bundle open/validate/render.
+ */
+export function carryForwardComment(bundlePath, comment) {
+    const alreadyCarried = readLog(bundlePath).some((entry) => entry.type === 'raised' && entry.id === comment.id);
+    if (alreadyCarried)
+        return;
+    appendEntry(bundlePath, {
+        type: 'raised',
+        id: comment.id,
+        createdAt: comment.createdAt,
+        body: comment.body,
+        target: comment.target,
+        kind: comment.kind,
+    });
+}
 /** Reduces the append-only log into the current set of Comments. */
 export function readQuestions(bundlePath) {
     const comments = new Map();

package/dist/renderer/render.js

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path';
+import { collectCarriedReviewContent, createCaches, readChain } from "../bundle/carry-forward.js";
 import { ALLOWED_ASSET_EXTENSIONS } from "../security/asset-path.js";
 /**
  * The app never launches a Generator itself (per framework.md) — this only
@@ -123,7 +124,22 @@ export function render(document, patch, diagnostics, bundlePath) {
         list.push(d);
         diagnosticsByPath.set(path, list);
     }
-    const groups = [...(document.behavioralGroups ?? [])]
+    // Both `chain` below and `collectCarriedReviewContent` read the same chain.json —
+    // sharing one `Caches` instance across both calls (scoped to this single `render()`
+    // call, then discarded) makes that one disk read either way, without ever letting the
+    // read survive past this call to go stale on a later one.
+    const caches = createCaches();
+    const chain = readChain(bundlePath, caches);
+    // Behavioral Groups/Annotations from earlier rounds the incremental patch doesn't
+    // touch surface here unchanged (framework.md's "slim rounds") — round N's own
+    // document only needs fresh ones for genuinely new material.
+    const carried = collectCarriedReviewContent(bundlePath, document, caches);
+    const effectiveDocument = {
+        ...document,
+        behavioralGroups: [...(document.behavioralGroups ?? []), ...carried.behavioralGroups],
+        annotations: [...(document.annotations ?? []), ...carried.annotations],
+    };
+    const groups = [...(effectiveDocument.behavioralGroups ?? [])]
         .sort((a, b) => a.order - b.order)
         .map((g) => ({
         id: g.id,
@@ -153,7 +169,7 @@ export function render(document, patch, diagnostics, bundlePath) {
     const files = orderedPaths
         .map((path) => patchFileByPath.get(path))
         .filter((f) => f !== undefined)
-        .map((f) => renderFile(f, document, diagnosticsByPath.get(f.path) ?? []));
+        .map((f) => renderFile(f, effectiveDocument, diagnosticsByPath.get(f.path) ?? []));
     const attachedPaths = new Set(patch.files.map((f) => f.path));
     const bundleLevelDiagnostics = diagnostics.filter((d) => {
         const path = diagnosticPath(d);
@@ -161,12 +177,13 @@ export function render(document, patch, diagnostics, bundlePath) {
     });
     return {
         comparison: document.comparison,
+        round: chain?.round ?? 1,
         groups,
         files,
         diagnostics: bundleLevelDiagnostics,
         generatorPrompt: buildGeneratorPrompt(bundlePath),
         answers: document.answers ?? [],
-        summary: renderSummary(document, attachedPaths),
+        summary: renderSummary(effectiveDocument, attachedPaths),
     };
 }
 /** Dangling ids/paths are dropped rather than diagnosed — same treatment as evidence/verification targetIds. */