@anureo/code-review 0.0.0-stage → 0.3.0

package/src/report.d.ts

@@ -0,0 +1,5 @@
+import type { ReviewReport } from "./results.js";
+/** Render a ReviewReport as text with a trailing newline. Sections follow the report's module and
+ * angle order and retain failed coverage, fix outcomes and observer errors. The caller owns output.
+ * The CLI's reviewAndPrintReport writes this text to stdout when JSON output is disabled. */
+export declare function formatReport(report: ReviewReport): string;

package/src/report.js

@@ -0,0 +1,80 @@
+/** Render a ReviewReport as text with a trailing newline. Sections follow the report's module and
+ * angle order and retain failed coverage, fix outcomes and observer errors. The caller owns output.
+ * The CLI's reviewAndPrintReport writes this text to stdout when JSON output is disabled. */
+export function formatReport(report) {
+    const lines = [
+        `Code review: ${report.status}`,
+        `Run: ${report.runId}`,
+        `Workflow storage: ${report.workflowDirectory}`,
+        `Directory: ${report.cwd}`,
+        `Scope: ${report.scope.moduleIds.length} of ${report.plan.modules.length} planned modules; angles: ${report.scope.angleIds.join(', ')}`,
+        '', report.plan.summary,
+    ];
+    for (const outcome of report.modules) {
+        appendModuleOutcome(lines, outcome);
+    }
+    if (report.progressErrors.length > 0) {
+        lines.push('', '## Progress reporting errors');
+        for (const error of report.progressErrors) {
+            appendFailure(lines, { error, prefix: '- ' });
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Keep the original review, fix and final verification together under the module heading. */
+function appendModuleOutcome(lines, outcome) {
+    const { review } = outcome;
+    lines.push('', `## ${review.module.name} (${review.module.id})`);
+    appendAngleReviews(lines, review.angles, '###');
+    if (outcome.fix)
+        appendFix(lines, outcome.fix);
+    if (outcome.verification) {
+        lines.push('', '### Review after fixes');
+        appendAngleReviews(lines, outcome.verification.angles, '####');
+    }
+}
+/** Render angle outcomes in report order with caller-selected heading depth, retaining failures. */
+function appendAngleReviews(lines, angles, headingPrefix) {
+    for (const result of angles) {
+        lines.push('', `${headingPrefix} ${result.angle.title}`);
+        appendAngleResult(lines, result);
+    }
+}
+/** Distinguish failed coverage from a completed angle with no findings. Indent continuation
+ * lines so multiline finding bodies and suggestions stay under their finding. */
+function appendAngleResult(lines, result) {
+    if (result.status === 'failed') {
+        appendFailure(lines, { error: result.error, prefix: 'Review failed: ',
+            unknownOutcomeMessage: 'Agent execution outcome is unknown.' });
+        return;
+    }
+    if (result.findings.length === 0) {
+        lines.push('No findings.');
+        return;
+    }
+    const indent = (text) => text.replace(/\n/g, '\n  ');
+    for (const finding of result.findings) {
+        lines.push(`- [${finding.severity}] ${finding.title} (${finding.file}:${finding.lineStart}-${finding.lineEnd})`, `  ${indent(finding.body)}`, `  Suggestion: ${indent(finding.suggestion)}`);
+    }
+}
+/** Show recorded edits even if a later failure made the fix incomplete. */
+function appendFix(lines, fix) {
+    lines.push('', `### Fix: ${fix.status}`, fix.summary);
+    if (fix.changedFiles.length > 0)
+        lines.push(`Changed files: ${fix.changedFiles.join(', ')}`);
+    if (fix.error) {
+        appendFailure(lines, { error: fix.error, prefix: 'Fix failed: ',
+            unknownOutcomeMessage: 'The backend could not confirm the fix agent outcome.' });
+    }
+}
+/** Append a failure's message, optional code and validation issues in that order. Review and fix
+ * sections supply their own uncertainty notices. The progress section leaves the notice unset. */
+function appendFailure(lines, input) {
+    const { error, prefix, unknownOutcomeMessage } = input;
+    lines.push(`${prefix}${error.message}${error.code ? ` [${error.code}]` : ''}`);
+    for (const issue of error.issues ?? []) {
+        lines.push(`Validation issue: ${JSON.stringify(issue.path)} [${issue.code}]`);
+    }
+    if (error.outcomeUnknown && unknownOutcomeMessage)
+        lines.push(unknownOutcomeMessage);
+}

package/src/results.d.ts

@@ -0,0 +1,69 @@
+import type { ReviewAngle } from "./angles.js";
+import type { ReviewFailure } from "./errors.js";
+import type { Finding, ModulePlan, ReviewModule } from "./schema.js";
+/** Check whether a fix wrote validated changes to the original work tree and inspect any failure. */
+export interface FixReport {
+    /** 'not-needed' means no findings in a complete review. 'skipped' covers incomplete reviews,
+     * a prior fix failure or no observed edits. 'applied' means validated edits reached the original
+     * work tree and cleanup finished. Check verification for remaining findings. */
+    status: 'not-needed' | 'skipped' | 'applied' | 'failed';
+    /** Agent summary when reconciliation produced an outcome, or a host explanation. */
+    summary: string;
+    /** Sorted paths relative to the review directory, applied to the original work tree.
+     * These can be present if failure occurred after integration, such as during cleanup. */
+    changedFiles: string[];
+    /** Normalized failure for 'failed'; null for other statuses. */
+    error: ReviewFailure | null;
+}
+/** Inspect an angle's validated findings or the failure that left its coverage incomplete. */
+export type AngleReview = {
+    angle: ReviewAngle;
+} & ({
+    status: 'completed';
+    findings: Finding[];
+} | {
+    status: 'failed';
+    error: ReviewFailure;
+});
+/** Read one module's assignment and outcomes in selected angle order, including failed slots. */
+export interface ModuleReview {
+    module: ReviewModule;
+    angles: AngleReview[];
+}
+/** Compare a module's original review, queued fix, and verification of the final work tree. */
+export interface ModuleOutcome {
+    review: ModuleReview;
+    /** Null when no fix was requested or the lifecycle task returned no outcome. */
+    fix: FixReport | null;
+    /** Review after all queued fixes settle, including the effects of edits from other modules.
+     * Null if no fix outcome recorded changed files. A fix that fails after integration can
+     * still trigger verification. */
+    verification: ModuleReview | null;
+}
+/** Returned after review, requested fixes and any final verification settle. Module order follows
+ * the selected plan; callers inspect status and failures before treating findingCount as complete. */
+export interface ReviewReport {
+    /** Durable workflow identity; records are retained beneath workflowDirectory/runId. */
+    runId: string;
+    /** Absolute workflow storage root, which can be outside the source directory. */
+    workflowDirectory: string;
+    /** Canonical absolute directory reviewed by the agents. */
+    cwd: string;
+    /** 'incomplete' when any recorded angle or fix failed, or the workflow reports incomplete
+     * execution. A 'completed' report can still contain findings or skipped fixes. */
+    status: 'completed' | 'incomplete';
+    /** Full validated analysis plan, including modules omitted by selection or limits. */
+    plan: ModulePlan;
+    /** Reviewed module IDs in plan order and selected angle IDs in caller/default order. */
+    scope: {
+        moduleIds: string[];
+        angleIds: string[];
+    };
+    modules: ModuleOutcome[];
+    /** Synchronous exceptions from onProgress, in delivery order. These diagnostics do not affect status. */
+    progressErrors: ReviewFailure[];
+    /** Sum of findings from completed angles, using each module's verification when present and its
+     * original review otherwise. Failed angles contribute zero. The CLI uses this count to choose
+     * exit code 0 or 1 for a completed report. */
+    findingCount: number;
+}

package/src/review-execution.d.ts

@@ -0,0 +1,52 @@
+import { type Client } from '@anureo/sdk';
+import type { ReviewAngle } from "./angles.js";
+import type { ReviewProgress } from "./progress.js";
+import type { ModuleReview } from "./results.js";
+import { type ReviewModule } from "./schema.js";
+/** Prepared run settings shared by analysis, angle execution and fix scheduling.
+ * The client remains borrowed. reviewCode supplies an observer that collects synchronous exceptions. */
+export interface ReviewExecutionOptions {
+    client: Client;
+    /** Canonical absolute source directory established by prepareReview. */
+    cwd: string;
+    /** Git root used to isolate agents in fix mode. Omission runs agents in cwd. */
+    repositoryRoot?: string;
+    /** Absolute workflow storage root excluded from source validation. */
+    directory: string;
+    model?: string;
+    focus?: string;
+    /** Git metadata fingerprint embedded in prompts. Null omits provenance. Sources can change after sampling. */
+    sourceVersion: string | null;
+    angles: readonly ReviewAngle[];
+    concurrency: number;
+    onProgress?: (event: ReviewProgress) => void;
+}
+/** Phase used by angle prompts and progress events. Verification starts after the writer queue drains. */
+export type ReviewPhase = 'review' | 'verification';
+/** Await work under the run permit pool, propagating its value or rejection. The callback
+ * owns its resources and should finish cleanup before settling so the permit covers that work. */
+export type Schedule = <T>(execute: () => Promise<T>) => Promise<T>;
+/** Dispatch a module's angles with the run's shared capacity. Initial review takes a planned
+ * module. Verification takes its original review, whose completed findings are matched by angle ID. */
+export type ModuleReviewInput = {
+    options: ReviewExecutionOptions;
+    schedule: Schedule;
+} & ({
+    phase: 'review';
+    module: ReviewModule;
+} | {
+    phase: 'verification';
+    previous: ModuleReview;
+});
+/** Create one permit pool for reviewCode's prevalidated positive concurrency limit.
+ * reviewModule uses it for individual angles and runModuleFix uses it for the queue head.
+ * Each settled operation hands its permit to the oldest waiter or returns it to the pool. */
+export declare function createReviewSchedule(limit: number): Schedule;
+/** Return a module's coverage in angle order after every scheduled angle settles.
+ * reviewModuleLifecycle passes this coverage to the optional fix queue. verifyFinalTree stores
+ * it for the final report. Rejected tasks become failed slots. Fatal agent errors are also
+ * recorded by workflow and can cause reviewCode to reject. */
+export declare function reviewModule(input: ModuleReviewInput): Promise<ModuleReview>;
+/** Supply failed angle slots in configured order when reviewModules or verifyFinalTree has no
+ * result for a module. Each caller stores the fallback in its corresponding report slot. */
+export declare function failedModuleReview(angles: readonly ReviewAngle[], module: ReviewModule, message: string): ModuleReview;

package/src/review-execution.js

@@ -0,0 +1,81 @@
+import { HarnessSdkError } from '@anureo/sdk';
+import { agent, parallel } from '@anureo/workflow';
+import { reviewFailure } from "./errors.js";
+import { buildReviewPrompt } from "./prompts.js";
+import { reviewOutputSchema } from "./schema.js";
+import { validateFindings, validateOutput } from "./validation.js";
+import { withAgentWorktree } from "./worktree.js";
+/** Create one permit pool for reviewCode's prevalidated positive concurrency limit.
+ * reviewModule uses it for individual angles and runModuleFix uses it for the queue head.
+ * Each settled operation hands its permit to the oldest waiter or returns it to the pool. */
+export function createReviewSchedule(limit) {
+    let available = limit;
+    const waiting = [];
+    return async (execute) => {
+        if (available === 0)
+            await new Promise(resume => waiting.push(resume));
+        else
+            available--;
+        try {
+            return await execute();
+        }
+        finally {
+            const resume = waiting.shift();
+            if (resume)
+                resume();
+            else
+                available++;
+        }
+    };
+}
+/** Return a module's coverage in angle order after every scheduled angle settles.
+ * reviewModuleLifecycle passes this coverage to the optional fix queue. verifyFinalTree stores
+ * it for the final report. Rejected tasks become failed slots. Fatal agent errors are also
+ * recorded by workflow and can cause reviewCode to reject. */
+export async function reviewModule(input) {
+    const { options, phase, schedule } = input;
+    const module = phase === 'review' ? input.module : input.previous.module;
+    const previousAngles = phase === 'verification' ? input.previous.angles : undefined;
+    const results = await parallel(options.angles.map(angle => () => schedule(() => reviewAngle({
+        options, module, angle, phase,
+        original: previousAngles?.find(value => value.angle.id === angle.id),
+    }))));
+    // parallel preserves positions; retain coverage when a task fails outside its agent call.
+    return { module, angles: options.angles.map((angle, index) => results[index] ??
+            failedAngleReview(angle, `Angle task for ${angle.id} failed before producing a result`)) };
+}
+/** Supply failed angle slots in configured order when reviewModules or verifyFinalTree has no
+ * result for a module. Each caller stores the fallback in its corresponding report slot. */
+export function failedModuleReview(angles, module, message) {
+    return { module, angles: angles.map(angle => failedAngleReview(angle, message)) };
+}
+/** Run one angle for reviewModule while it holds a permit. Validate findings in the same source
+ * view the agent used and wait for any temporary checkout cleanup. Agent, validation
+ * and worktree failures become failed coverage. A failure preparing the prompt or emitting an
+ * event rejects the task for reviewModule's positional fallback. */
+async function reviewAngle({ options, module, angle, phase, original }) {
+    const progress = { stage: phase, moduleId: module.id, angleId: angle.id };
+    options.onProgress?.({ ...progress, status: 'started' });
+    const prompt = buildReviewPrompt({ ...options, phase, module, angle, original });
+    let result;
+    try {
+        const findings = await withAgentWorktree({ root: options.repositoryRoot, cwd: options.cwd, directory: options.directory }, async (cwd, directory) => {
+            const output = await agent(prompt, {
+                client: options.client, cwd, model: options.model, schema: reviewOutputSchema,
+            });
+            if (output === null)
+                throw new HarnessSdkError('REVIEW_AGENT_INCOMPLETE', 'Review agent returned no result');
+            return validateOutput(() => validateFindings(cwd, module, output.findings, directory));
+        });
+        result = { angle, status: 'completed', findings };
+    }
+    catch (cause) {
+        result = { angle, status: 'failed', error: reviewFailure(cause) };
+    }
+    options.onProgress?.({ ...progress, status: result.status === 'completed' ? 'completed' : 'failed' });
+    return result;
+}
+/** Preserve an angle slot when parallel work returned no result, using a normalized local failure. */
+function failedAngleReview(angle, message) {
+    return { angle, status: 'failed', error: reviewFailure(new Error(message)) };
+}

package/src/review-report.d.ts

@@ -0,0 +1,21 @@
+import type { ReviewFailure } from "./errors.js";
+import type { ModuleOutcome, ReviewReport } from "./results.js";
+import type { ModulePlan, ReviewModule } from "./schema.js";
+/** Build the report from settled outcomes supplied in selected plan order. Count each module's
+ * verification when present, otherwise its original review. reviewCode returns this object from
+ * the workflow body for persistence, then applies any workflow status downgrade to its library
+ * result. This builder retains the supplied outcome and progress arrays by reference. */
+export declare function buildReviewReport(input: {
+    runId: string;
+    execution: {
+        directory: string;
+        cwd: string;
+        angles: readonly {
+            id: string;
+        }[];
+    };
+    plan: ModulePlan;
+    selectedModules: readonly ReviewModule[];
+    outcomes: ModuleOutcome[];
+    progressErrors: ReviewFailure[];
+}): ReviewReport;

package/src/review-report.js

@@ -0,0 +1,30 @@
+/** Build the report from settled outcomes supplied in selected plan order. Count each module's
+ * verification when present, otherwise its original review. reviewCode returns this object from
+ * the workflow body for persistence, then applies any workflow status downgrade to its library
+ * result. This builder retains the supplied outcome and progress arrays by reference. */
+export function buildReviewReport(input) {
+    const { runId, execution, plan, selectedModules, outcomes, progressErrors } = input;
+    const findingCount = outcomes.reduce((count, outcome) => count + countFindings(outcome.verification ?? outcome.review), 0);
+    return {
+        runId,
+        workflowDirectory: execution.directory,
+        cwd: execution.cwd,
+        plan,
+        modules: outcomes,
+        progressErrors,
+        scope: { moduleIds: selectedModules.map(module => module.id), angleIds: execution.angles.map(angle => angle.id) },
+        status: outcomes.every(moduleOutcomeComplete) ? 'completed' : 'incomplete',
+        findingCount,
+    };
+}
+/** Require completed angle coverage and no failed fix; a skipped fix alone does not fail the outcome. */
+function moduleOutcomeComplete(outcome) {
+    const anglesComplete = (review) => review.angles.every(angle => angle.status === 'completed');
+    return anglesComplete(outcome.review)
+        && (outcome.verification === null || anglesComplete(outcome.verification))
+        && outcome.fix?.status !== 'failed';
+}
+/** Count only observed findings; failed angle slots contribute zero without implying complete coverage. */
+function countFindings(review) {
+    return review.angles.reduce((count, angle) => count + (angle.status === 'completed' ? angle.findings.length : 0), 0);
+}

package/src/review.d.ts

@@ -0,0 +1,16 @@
+import { type ReviewOptions } from "./options.js";
+import type { ReviewReport } from "./results.js";
+export type { ReviewFailure } from "./errors.js";
+export { DEFAULT_REVIEW_CONCURRENCY } from "./options.js";
+export type { ReviewOptions } from "./options.js";
+export type { ReviewProgress } from "./progress.js";
+export type { AngleReview, ModuleReview, ModuleOutcome, ReviewReport } from "./results.js";
+/** Analyze source modules, review selected angles and optionally apply fixes to the original
+ * work tree. If a fix reports changed files, recheck every selected module after the writers settle.
+ * Resolves with a report after workflow publication and lock release. Ordinary angle and fix
+ * failures are recorded in an incomplete report. Finding counts come from verification when
+ * it runs. Invalid options or module IDs, analysis failures and fatal execution or workflow
+ * storage failures reject.
+ * Synchronous observer exceptions are collected in the report's progressErrors. Keep the
+ * initialized client usable until the promise settles, then dispose it separately. */
+export declare function reviewCode(options: ReviewOptions): Promise<ReviewReport>;

package/src/review.js

@@ -0,0 +1,184 @@
+// Coordinates analysis, module review, serialized fixes and final verification.
+import { resolve } from 'node:path';
+import { HarnessSdkError } from '@anureo/sdk';
+import { agent, parallel, workflow } from '@anureo/workflow';
+import { reviewFailure } from "./errors.js";
+import { fixFindings } from "./fix.js";
+import { reviewRepositoryRoot } from "./git.js";
+import { readGitStateFingerprint } from "./git-state.js";
+import { validateReviewOptions } from "./options.js";
+import { DEFAULT_WORKFLOW_DIRECTORY, resolveReviewDirectory } from "./paths.js";
+import { buildAnalysisPrompt, readOnlyInstructions } from "./prompts.js";
+import { createReviewSchedule, failedModuleReview, reviewModule } from "./review-execution.js";
+import { buildReviewReport } from "./review-report.js";
+import { modulePlanSchema } from "./schema.js";
+import { validateOutput, validatePlan } from "./validation.js";
+import { withAgentWorktree } from "./worktree.js";
+export { DEFAULT_REVIEW_CONCURRENCY } from "./options.js";
+/** Analyze source modules, review selected angles and optionally apply fixes to the original
+ * work tree. If a fix reports changed files, recheck every selected module after the writers settle.
+ * Resolves with a report after workflow publication and lock release. Ordinary angle and fix
+ * failures are recorded in an incomplete report. Finding counts come from verification when
+ * it runs. Invalid options or module IDs, analysis failures and fatal execution or workflow
+ * storage failures reject.
+ * Synchronous observer exceptions are collected in the report's progressErrors. Keep the
+ * initialized client usable until the promise settles, then dispose it separately. */
+export async function reviewCode(options) {
+    const progressErrors = [];
+    const prepared = await prepareReview({ ...options, onProgress: event => {
+            try {
+                options.onProgress?.(event);
+            }
+            catch (cause) {
+                progressErrors.push(reviewFailure(cause));
+            }
+        } });
+    const { execution, fixRequested, moduleIds, maxModules } = prepared;
+    // Bump revision when the persisted input/checkpoint contract changes.
+    // sourceVersion carries the Git state fingerprint; backendConfiguration remains reserved.
+    const completed = await workflow({
+        name: 'code-review', revision: '8', directory: execution.directory, input: prepared.workflowInput,
+    }, async (run) => {
+        execution.onProgress?.({ stage: 'workflow', status: 'started', runId: run.runId, directory: execution.directory });
+        const plan = await analyzeModules(execution, prepared.analysisPrompt);
+        const selectedModules = selectModules({ plan, moduleIds, maxModules });
+        const schedule = createReviewSchedule(execution.concurrency);
+        const runFix = fixRequested
+            ? createFixRunner({ execution, schedule, permissionMode: options.fixPermissionMode })
+            : null;
+        const outcomes = await reviewModules({ execution, modules: selectedModules, schedule, runFix });
+        await verifyFinalTree({ execution, outcomes, schedule });
+        return buildReviewReport({ runId: run.runId, execution, plan, selectedModules, outcomes, progressErrors });
+    });
+    return { ...completed.result, status: completed.status === 'incomplete' ? 'incomplete' : completed.result.status };
+}
+/** Return plan-ordered outcomes to reviewCode after every module lifecycle and queued fix settles.
+ * Replace rejected lifecycles with failed coverage so final verification and reporting retain
+ * the selected scope. The enclosing workflow still rejects if it recorded a fatal error. */
+async function reviewModules({ execution, modules, schedule, runFix }) {
+    const results = await parallel(modules.map(module => () => reviewModuleLifecycle({ execution, module, schedule, runFix })));
+    return modules.map((module, index) => results[index] ?? {
+        review: failedModuleReview(execution.angles, module, `Module task for ${module.id} failed before producing a result`),
+        fix: null, verification: null,
+    });
+}
+/** Fill verification slots in place for reviewCode's report once reviewModules has drained the
+ * writers. A fix that reports changed files triggers a recheck of all selected modules because
+ * edits can affect callers elsewhere. Share one provenance value across the recheck and turn
+ * rejected module tasks into failed coverage. */
+async function verifyFinalTree({ execution, outcomes, schedule }) {
+    if (!outcomes.some(outcome => outcome.fix && outcome.fix.changedFiles.length > 0))
+        return;
+    const finalExecution = { ...execution, sourceVersion: await readGitStateFingerprint(execution.cwd) };
+    const verifications = await parallel(outcomes.map(outcome => () => reviewModule({
+        options: finalExecution, phase: 'verification', schedule, previous: outcome.review,
+    })));
+    for (const [index, outcome] of outcomes.entries()) {
+        outcome.verification = verifications[index] ?? failedModuleReview(execution.angles, outcome.review.module, `Verification task for ${outcome.review.module.id} failed before producing a result`);
+    }
+}
+/** Give reviewCode the requested modules in plan order, capped only after ID filtering.
+ * Throws for unknown requested IDs before any module review or fix starts. */
+function selectModules({ plan, moduleIds, maxModules }) {
+    const available = new Set(plan.modules.map(module => module.id));
+    const unknown = moduleIds?.filter(id => !available.has(id)) ?? [];
+    if (unknown.length > 0) {
+        throw new HarnessSdkError('REVIEW_MODULE_NOT_FOUND', `Unknown module ids: ${unknown.join(', ')}. Available: ${[...available].join(', ')}`);
+    }
+    const selected = moduleIds ? plan.modules.filter(module => moduleIds.includes(module.id)) : plan.modules;
+    return maxModules === undefined ? selected : selected.slice(0, maxModules);
+}
+/** Prepare execution settings and persisted identity inputs for reviewCode. Validate selections,
+ * resolve the source directory and require a Git root for fix mode before opening workflow
+ * storage or agent sessions. A failed preflight rejects the call. */
+async function prepareReview(options) {
+    const selection = validateReviewOptions(options);
+    const { fixRequested, concurrency, maxModules, moduleIds, angles } = selection;
+    const cwd = await resolveReviewDirectory(options.cwd);
+    const repositoryRoot = fixRequested ? await reviewRepositoryRoot(cwd) : undefined;
+    const version = await readGitStateFingerprint(cwd);
+    const analysisPrompt = buildAnalysisPrompt({ focus: options.focus, sourceVersion: version });
+    const directory = resolve(options.workflowDirectory ?? resolve(cwd, DEFAULT_WORKFLOW_DIRECTORY));
+    const execution = {
+        client: options.client, cwd, directory, model: options.model, focus: options.focus,
+        sourceVersion: version, repositoryRoot, angles, concurrency, onProgress: options.onProgress,
+    };
+    return { ...selection, execution, analysisPrompt, workflowInput: {
+            cwd, model: options.model ?? null, focus: options.focus ?? null, concurrency,
+            moduleIds: moduleIds ?? null, maxModules: maxModules ?? null, fix: fixRequested,
+            angles, instructions: readOnlyInstructions, analysisPrompt,
+            sourceVersion: version, backendConfiguration: null,
+        } };
+}
+/** Supply reviewCode with the normalized plan for module selection. In fix mode, validate paths
+ * first in the agent's checkout, then in the original tree where fixes will be applied.
+ * A missing result, failed validation or failed agent/worktree operation rejects before dispatch. */
+async function analyzeModules(execution, prompt) {
+    execution.onProgress?.({ stage: 'analysis', status: 'started' });
+    const plan = await withAgentWorktree({ root: execution.repositoryRoot, cwd: execution.cwd, directory: execution.directory }, async (cwd, directory) => {
+        const analysis = await agent(prompt, {
+            client: execution.client, cwd, model: execution.model, schema: modulePlanSchema,
+        });
+        if (analysis === null)
+            throw new HarnessSdkError('REVIEW_AGENT_INCOMPLETE', 'Module analysis failed: agent returned no result');
+        const localPlan = await validateOutput(() => validatePlan(cwd, analysis, directory));
+        return execution.repositoryRoot
+            ? validateOutput(() => validatePlan(execution.cwd, localPlan, execution.directory))
+            : localPlan;
+    });
+    execution.onProgress?.({ stage: 'analysis', status: 'completed' });
+    return plan;
+}
+/** Supply reviewModuleLifecycle with one fix queue. Lifecycles enqueue after their reviews
+ * complete, so fixes run in enqueue order and only the head competes for an agent permit.
+ * A failed fix report or rejection closes the queue to further writes. The current lifecycle
+ * receives the original report or rejection, and later lifecycles receive skipped reports. */
+function createFixRunner({ execution, schedule, permissionMode }) {
+    let tail = Promise.resolve();
+    let stoppedBy;
+    return (review) => {
+        const result = tail.then(async () => {
+            if (stoppedBy !== undefined) {
+                execution.onProgress?.({ stage: 'fix', status: 'skipped', moduleId: review.module.id });
+                return { status: 'skipped', summary: `Fix skipped because module ${stoppedBy}'s fix failed. Previously applied fixes remain in the original work tree.`,
+                    changedFiles: [], error: null };
+            }
+            const fix = await runModuleFix({ execution, schedule, permissionMode, review });
+            if (fix.status === 'failed')
+                stoppedBy = review.module.id;
+            return fix;
+        });
+        // Unexpected local failures must also stop queued writers. Workflow-level
+        // fatal errors retain their original cause in the engine's run state.
+        tail = result.then(() => undefined, () => { stoppedBy = review.module.id; });
+        return result;
+    };
+}
+/** Run the queue head under the shared permit. Capture provenance after acquiring capacity
+ * and forward fixFindings' synchronous progress to the run observer. The queue consumes the
+ * fix report or rejection after the permit is released. */
+function runModuleFix({ execution, schedule, permissionMode, review }) {
+    return schedule(async () => fixFindings({
+        sourceVersion: await readGitStateFingerprint(execution.cwd),
+        client: execution.client,
+        cwd: execution.cwd,
+        directory: execution.directory,
+        repositoryRoot: execution.repositoryRoot,
+        modules: [review],
+        model: execution.model,
+        ...(permissionMode !== undefined ? { permissionMode } : {}),
+        onProgress: status => execution.onProgress?.({ stage: 'fix', status, moduleId: review.module.id }),
+    }));
+}
+/** Return one initial review and its optional queued fix to reviewModules. The review's
+ * provenance is sampled at module dispatch, which may overlap fixes for other modules.
+ * Await the queued fix so reviewModules can drain writers and replace any rejected lifecycle
+ * with failed coverage before final verification. */
+async function reviewModuleLifecycle(options) {
+    const { execution, module, schedule, runFix } = options;
+    const review = await reviewModule({
+        options: { ...execution, sourceVersion: await readGitStateFingerprint(execution.cwd) }, module, phase: 'review', schedule,
+    });
+    const fix = runFix ? await runFix(review) : null;
+    return { review, fix, verification: null };
+}

package/src/schema.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+/** Read a source assignment from ReviewReport.plan or a module outcome. In returned reports,
+ * files are canonical, slash-separated paths relative to the review directory, with one owner
+ * per plan. The exact id identifies the module for selection, progress events and reports. */
+export type ReviewModule = z.infer<typeof moduleSchema>;
+/** Read the full validated analysis plan, including assignments omitted by review selection.
+ * Every listed file has one owner. The plan may omit reviewable source files. */
+export type ModulePlan = z.infer<typeof modulePlanSchema>;
+/** Read an issue from a completed angle. The canonical file path is relative to the review
+ * directory, and the 1-based inclusive range was checked against source at validation time.
+ * The body and suggested remedy are agent assessments. */
+export type Finding = z.infer<typeof findingSchema>;
+/** Internal structured response from the fix agent. applyFix takes the summary from the
+ * response and determines the report's changed files through Git reconciliation. */
+export type FixResult = z.infer<typeof fixResultSchema>;
+/** Internal structural schema for one analysis assignment; validatePlan checks source scope,
+ * canonical ownership and ID limits after structured output parsing. Unknown fields are rejected. */
+export declare const moduleSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    files: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/** Internal structured output contract submitted by analyzeModules; requires a nonempty plan
+ * and rejects unknown fields. Filesystem validity and ownership are checked by validatePlan. */
+export declare const modulePlanSchema: z.ZodObject<{
+    summary: z.ZodString;
+    modules: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        files: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Severity values accepted for Finding.severity.
+ * The findings schema and review prompt both derive their vocabulary from this list. */
+export declare const findingSeverities: readonly ["P0", "P1", "P2", "P3"];
+/** Internal finding shape used by reviewOutputSchema. Rejects unknown fields; validateFindings
+ * separately checks canonical module ownership and inclusive ranges against current source text. */
+export declare const findingSchema: z.ZodObject<{
+    severity: z.ZodEnum<{
+        P0: "P0";
+        P1: "P1";
+        P2: "P2";
+        P3: "P3";
+    }>;
+    title: z.ZodString;
+    body: z.ZodString;
+    suggestion: z.ZodString;
+    file: z.ZodString;
+    lineStart: z.ZodNumber;
+    lineEnd: z.ZodNumber;
+}, z.core.$strict>;
+/** Internal output schema supplied by reviewAngle for review and verification agents.
+ * An empty findings array is valid. validateFindings checks source locations after parsing. */
+export declare const reviewOutputSchema: z.ZodObject<{
+    findings: z.ZodArray<z.ZodObject<{
+        severity: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        title: z.ZodString;
+        body: z.ZodString;
+        suggestion: z.ZodString;
+        file: z.ZodString;
+        lineStart: z.ZodNumber;
+        lineEnd: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Internal output schema supplied by applyFix for the agent's result after editing sources.
+ * applyFix checks Git state and observed edits before applying a patch to the original tree. */
+export declare const fixResultSchema: z.ZodObject<{
+    summary: z.ZodString;
+    changedFiles: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;