@zq-silk/yui 0.6.0 → 0.6.2

package/dist/review/reviewFindingLedger.js

@@ -0,0 +1,545 @@
+import { createHash } from "node:crypto";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { isSemanticReviewRound } from "./reviewOutcomeClassifier.js";
+import { createReviewFinding, disposeReviewFinding, isReviewFindingBlocking, normalizeReviewFindingSeverity, redetectReviewFinding, resolveReviewFinding, reviewFindingStableKey, touchReviewFinding, validateReviewFinding } from "./reviewFinding.js";
+/** Resolves the durable feature flag; absent config defaults to shadow. */
+export function reviewFindingLedgerMode(config) {
+    const mode = config.review?.findingLedger;
+    return mode === "enforce" ? "enforce" : "shadow";
+}
+export const REVIEW_FINDINGS_RECONCILE_FAILED_EVENT = "review.findings-reconcile-failed";
+/**
+ * Extracts reported findings from a completed Round.  The reviewer's JSON
+ * report is the authoritative source; panel Rounds fall back to the findings
+ * attached to their ExecutionGroup lane results.  A malformed or free-text
+ * report yields no findings (the raw report stays authoritative evidence).
+ */
+export function extractReportedFindings(round) {
+    const fromReport = extractFindingsFromReportJson(round.report ?? "");
+    if (fromReport.length > 0)
+        return fromReport;
+    return extractFindingsFromLanes(round);
+}
+function extractFindingsFromReportJson(report) {
+    let parsed;
+    try {
+        parsed = JSON.parse(report);
+    }
+    catch {
+        return [];
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return [];
+    const record = parsed;
+    if (!Array.isArray(record.findings))
+        return [];
+    return record.findings.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry))
+            return [];
+        const finding = entry;
+        const summary = typeof finding.summary === "string" && finding.summary.trim().length > 0
+            ? finding.summary.trim()
+            : typeof finding.title === "string" && finding.title.trim().length > 0
+                ? finding.title.trim()
+                : null;
+        if (summary === null)
+            return [];
+        let severity;
+        try {
+            severity = normalizeReviewFindingSeverity(finding.severity);
+        }
+        catch {
+            return [];
+        }
+        const status = finding.status === "resolved" ? "resolved" : "open";
+        const title = typeof finding.title === "string" && finding.title.trim().length > 0
+            ? finding.title.trim()
+            : summary;
+        const invariant = typeof finding.invariant === "string" && finding.invariant.trim().length > 0
+            ? finding.invariant.trim()
+            : typeof finding.category === "string" && finding.category.trim().length > 0
+                ? finding.category.trim()
+                : "review-finding";
+        return [{
+                ...(typeof finding.id === "string" && finding.id.trim().length > 0
+                    ? { sourceId: finding.id.trim() }
+                    : {}),
+                severity,
+                status,
+                invariant,
+                title,
+                affectedPaths: stringList(finding.paths ?? finding.affectedPaths),
+                affectedSymbols: stringList(finding.symbols ?? finding.affectedSymbols),
+                evidence: stringList(finding.evidence)
+            }];
+    });
+}
+function extractFindingsFromLanes(round) {
+    const lanes = round.executionGroup?.lanes ?? [];
+    return lanes.flatMap((lane) => {
+        const findings = lane.result?.findings ?? [];
+        return findings.flatMap((finding) => {
+            let severity;
+            try {
+                severity = normalizeReviewFindingSeverity(finding.severity);
+            }
+            catch {
+                return [];
+            }
+            return [{
+                    sourceId: finding.id,
+                    severity,
+                    status: finding.status === "resolved" ? "resolved" : "open",
+                    invariant: "review-finding",
+                    title: finding.summary,
+                    affectedPaths: [],
+                    affectedSymbols: [],
+                    evidence: []
+                }];
+        });
+    });
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+        .map((entry) => entry.trim());
+}
+/**
+ * Reconciles one completed Round's findings into the Task ledger.  Stable-key
+ * matches update the existing record; ambiguous matches (multiple records with
+ * the same key) create a `mergeRequired` record instead of silently merging.
+ * Infra (failed) Rounds are skipped without touching the ledger.
+ */
+export function reconcileReviewFindings(store, taskId, roundId, now) {
+    const round = store.getReviewRound(taskId, roundId);
+    if (round === null) {
+        return { roundId, skipped: true, reason: "ReviewRound not found.", created: [], updated: [], conflicts: [] };
+    }
+    if (!isSemanticReviewRound(round)) {
+        return {
+            roundId,
+            skipped: true,
+            reason: "ReviewRound is an execution-attempt failure, not a semantic report.",
+            created: [],
+            updated: [],
+            conflicts: []
+        };
+    }
+    const extracted = extractReportedFindings(round);
+    if (extracted.length === 0) {
+        return { roundId, skipped: true, reason: "ReviewRound report carries no findings.", created: [], updated: [], conflicts: [] };
+    }
+    const ledger = store.listReviewFindings(taskId);
+    const created = [];
+    const updated = [];
+    const conflicts = [];
+    for (const entry of extracted) {
+        const stableKey = reviewFindingStableKey({
+            invariant: entry.invariant,
+            primaryPath: entry.affectedPaths[0],
+            primarySymbol: entry.affectedSymbols[0],
+            title: entry.title
+        });
+        const matches = ledger.filter((finding) => finding.stableKey === stableKey);
+        if (matches.length === 1) {
+            const existing = matches[0];
+            const next = entry.status === "resolved"
+                ? resolveReviewFinding(existing, {
+                    reviewRoundId: round.id,
+                    evidence: entry.evidence,
+                    now
+                })
+                : existing.disposition === "accepted-risk"
+                    || existing.disposition === "not-actionable"
+                    || existing.disposition === "superseded"
+                    ? touchReviewFinding(existing, {
+                        reviewRoundId: round.id,
+                        evidence: entry.evidence,
+                        now
+                    })
+                    : redetectReviewFinding(existing, {
+                        reviewRoundId: round.id,
+                        evidence: entry.evidence,
+                        now
+                    });
+            if (next !== existing) {
+                store.saveReviewFinding(taskId, next);
+                updated.push(next);
+            }
+            continue;
+        }
+        if (matches.length > 1) {
+            // Stable-key collision: keep every evidence trail and require an explicit
+            // Leader merge instead of silently overwriting either record.
+            const existingConflict = matches.find((finding) => finding.mergeRequired === true);
+            if (existingConflict !== undefined) {
+                // A merge-required record already exists for this stable key; refresh
+                // its evidence and last-Round pointer instead of creating unbounded
+                // duplicate conflict records.
+                const refreshed = touchReviewFinding(existingConflict, {
+                    reviewRoundId: round.id,
+                    evidence: entry.evidence,
+                    now
+                });
+                if (refreshed !== existingConflict) {
+                    store.saveReviewFinding(taskId, refreshed);
+                    updated.push(refreshed);
+                }
+                continue;
+            }
+            const conflict = createReviewFinding(store.nextReviewFindingId(taskId), taskId, {
+                ...(entry.sourceId === undefined ? {} : { sourceId: entry.sourceId }),
+                stableKey,
+                severity: entry.severity,
+                invariant: entry.invariant,
+                title: entry.title,
+                affectedPaths: entry.affectedPaths,
+                affectedSymbols: entry.affectedSymbols,
+                evidence: entry.evidence,
+                reviewRoundId: round.id
+            }, now);
+            const flagged = validateReviewFinding({ ...conflict, mergeRequired: true });
+            store.saveReviewFinding(taskId, flagged);
+            conflicts.push(flagged);
+            continue;
+        }
+        const createdFinding = createReviewFinding(store.nextReviewFindingId(taskId), taskId, {
+            ...(entry.sourceId === undefined ? {} : { sourceId: entry.sourceId }),
+            stableKey,
+            severity: entry.severity,
+            invariant: entry.invariant,
+            title: entry.title,
+            affectedPaths: entry.affectedPaths,
+            affectedSymbols: entry.affectedSymbols,
+            evidence: entry.evidence,
+            reviewRoundId: round.id
+        }, now);
+        store.saveReviewFinding(taskId, createdFinding);
+        created.push(createdFinding);
+    }
+    store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, "review.findings-reconciled", {
+        reviewRoundId: round.id,
+        created: String(created.length),
+        updated: String(updated.length),
+        conflicts: String(conflicts.length)
+    }, now));
+    return { roundId, skipped: false, created, updated, conflicts };
+}
+/**
+ * Reconciles a delivered Review without making ledger availability a
+ * precondition for preserving the reviewer's free-form report. A ledger
+ * read/write failure is recorded as a Task event; `enforce` completion fails
+ * closed until the Leader recovers the ledger.
+ */
+export function reconcileReviewFindingsAfterReview(store, taskId, roundId, now) {
+    try {
+        return reconcileReviewFindings(store, taskId, roundId, now);
+    }
+    catch (error) {
+        const reason = `Review finding ledger is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+        store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, REVIEW_FINDINGS_RECONCILE_FAILED_EVENT, { reviewRoundId: roundId, reason }, now));
+        return {
+            roundId,
+            skipped: true,
+            reason,
+            created: [],
+            updated: [],
+            conflicts: []
+        };
+    }
+}
+/** True when a semantic Review could not be reconciled into the ledger. */
+export function reviewFindingLedgerWriteFailed(store, taskId) {
+    const latestByRound = new Map();
+    for (const event of store.listEvents(taskId)) {
+        if (event.type !== REVIEW_FINDINGS_RECONCILE_FAILED_EVENT
+            && event.type !== "review.findings-reconciled") {
+            continue;
+        }
+        const reviewRoundId = event.payload.reviewRoundId;
+        if (reviewRoundId !== undefined)
+            latestByRound.set(reviewRoundId, event);
+    }
+    return [...latestByRound.values()]
+        .some((event) => event.type === REVIEW_FINDINGS_RECONCILE_FAILED_EVENT);
+}
+/** Applies one explicit Leader disposition to a finding. */
+export function dispositionReviewFinding(store, taskId, findingId, command) {
+    const existing = store.getReviewFinding(taskId, findingId);
+    if (existing === null) {
+        throw new Error(`ReviewFinding not found: ${taskId}/${findingId}.`);
+    }
+    const next = disposeReviewFinding(existing, {
+        disposition: command.disposition,
+        by: command.by,
+        ...(command.note === undefined ? {} : { note: command.note }),
+        ...(command.workItemId === undefined
+            && command.commit === undefined
+            && command.verification === undefined
+            ? {}
+            : {
+                repair: {
+                    ...(command.workItemId === undefined ? {} : { workItemId: command.workItemId }),
+                    ...(command.commit === undefined ? {} : { commit: command.commit }),
+                    ...(command.verification === undefined ? {} : { verification: command.verification })
+                }
+            }),
+        ...(command.supersededBy === undefined ? {} : { supersededBy: command.supersededBy }),
+        now: command.now
+    });
+    store.saveReviewFinding(taskId, next);
+    store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, "review.finding-dispositioned", {
+        reviewFindingId: next.id,
+        disposition: next.disposition,
+        by: command.by
+    }, command.now));
+    return next;
+}
+/**
+ * Groups open P1/P2 findings into repair waves by file/symbol/invariant
+ * overlap.  Findings sharing an affected path, symbol, or invariant land in
+ * the same group (union-find), so one WorkItem repairs one overlapping set
+ * while disjoint groups can run in parallel.
+ */
+export function planRepairGroups(store, taskId) {
+    const open = store.listReviewFindings(taskId)
+        .filter((finding) => finding.disposition === "open"
+        && (finding.severity === "p1" || finding.severity === "p2"))
+        .sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true }));
+    const parent = new Map(open.map((finding) => [finding.id, finding.id]));
+    const root = (id) => {
+        let current = id;
+        while (parent.get(current) !== current) {
+            current = parent.get(current);
+        }
+        let cursor = id;
+        while (parent.get(cursor) !== cursor) {
+            const next = parent.get(cursor);
+            parent.set(cursor, current);
+            cursor = next;
+        }
+        return current;
+    };
+    const union = (left, right) => {
+        const leftRoot = root(left);
+        const rightRoot = root(right);
+        if (leftRoot !== rightRoot)
+            parent.set(rightRoot, leftRoot);
+    };
+    const byPath = new Map();
+    const bySymbol = new Map();
+    const byInvariant = new Map();
+    for (const finding of open) {
+        for (const path of finding.affectedPaths) {
+            const seen = byPath.get(path);
+            if (seen === undefined)
+                byPath.set(path, finding.id);
+            else
+                union(seen, finding.id);
+        }
+        for (const symbol of finding.affectedSymbols) {
+            const seen = bySymbol.get(symbol);
+            if (seen === undefined)
+                bySymbol.set(symbol, finding.id);
+            else
+                union(seen, finding.id);
+        }
+        // Issue 06: only union on a real invariant.  Findings that lack an
+        // explicit invariant/category all share the fallback "review-finding"
+        // label; unioning on it would collapse sparse reports into one group and
+        // defeat parallel repair.
+        if (finding.invariant !== "review-finding") {
+            const seen = byInvariant.get(finding.invariant);
+            if (seen === undefined)
+                byInvariant.set(finding.invariant, finding.id);
+            else
+                union(seen, finding.id);
+        }
+    }
+    const groups = new Map();
+    for (const finding of open) {
+        const key = root(finding.id);
+        const members = groups.get(key) ?? [];
+        members.push(finding);
+        groups.set(key, members);
+    }
+    return [...groups.values()]
+        .map((findings) => ({
+        groupKey: findings.map(({ id }) => id).join("+"),
+        findings,
+        findingIds: findings.map(({ id }) => id),
+        affectedPaths: [...new Set(findings.flatMap(({ affectedPaths }) => affectedPaths))].sort(),
+        affectedSymbols: [...new Set(findings.flatMap(({ affectedSymbols }) => affectedSymbols))].sort(),
+        invariants: [...new Set(findings.map(({ invariant }) => invariant))].sort()
+    }))
+        .sort((left, right) => left.groupKey.localeCompare(right.groupKey, undefined, { numeric: true }));
+}
+/**
+ * Completion gate: open (or repair-pending) P1/P2 findings block Task
+ * completion under `enforce`.  P3/backlog findings never block.
+ */
+export function blockingOpenFindings(store, taskId) {
+    return store.listReviewFindings(taskId)
+        .filter(isReviewFindingBlocking)
+        .sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true }));
+}
+/** True when the completion gate must fail closed for this Task. */
+export function completionGateBlocked(store, taskId) {
+    if (reviewFindingLedgerMode(store.getConfig()) !== "enforce")
+        return false;
+    return reviewFindingLedgerWriteFailed(store, taskId)
+        || blockingOpenFindings(store, taskId).length > 0;
+}
+export function summarizeFindingLedger(store, taskId) {
+    const findings = store.listReviewFindings(taskId)
+        .sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true }));
+    const byDisposition = (disposition) => findings.filter((finding) => finding.disposition === disposition);
+    return {
+        total: findings.length,
+        open: byDisposition("open"),
+        fixedPendingReview: byDisposition("fixed-pending-review"),
+        verifiedFixed: byDisposition("verified-fixed"),
+        acceptedRisk: byDisposition("accepted-risk"),
+        notActionable: byDisposition("not-actionable"),
+        superseded: byDisposition("superseded"),
+        blocking: findings.filter(isReviewFindingBlocking),
+        mergeRequired: findings.filter((finding) => finding.mergeRequired === true)
+    };
+}
+/**
+ * Renders the ledger summary as the incremental Review context block: it
+ * replaces repeated full-history restatement while still listing every
+ * disposition class the final report must account for.
+ */
+export function renderFindingLedgerContext(summary) {
+    const lines = ["Finding ledger:"];
+    lines.push(`- total: ${summary.total}`);
+    const renderList = (label, findings) => {
+        if (findings.length === 0)
+            return;
+        lines.push(`- ${label}:`);
+        for (const finding of findings) {
+            lines.push(`  - ${finding.id} [${finding.severity}] ${finding.title}`
+                + ` (invariant: ${finding.invariant}; first: ${finding.firstReviewRoundId}; last: ${finding.lastReviewRoundId})`);
+            if (finding.repair !== undefined) {
+                const repairParts = [
+                    finding.repair.workItemId === undefined ? "" : `work-item=${finding.repair.workItemId}`,
+                    finding.repair.commit === undefined ? "" : `commit=${finding.repair.commit}`,
+                    finding.repair.verification === undefined ? "" : `verification=${finding.repair.verification}`
+                ].filter((part) => part.length > 0);
+                if (repairParts.length > 0)
+                    lines.push(`    repair: ${repairParts.join("; ")}`);
+            }
+        }
+    };
+    renderList("verified-fixed", summary.verifiedFixed);
+    renderList("open (new/repair pending)", summary.open);
+    renderList("fixed-pending-review", summary.fixedPendingReview);
+    renderList("accepted-risk", summary.acceptedRisk);
+    renderList("not-actionable (backlog)", summary.notActionable);
+    renderList("superseded", summary.superseded);
+    if (summary.mergeRequired.length > 0) {
+        lines.push(`- merge-required: ${summary.mergeRequired.map(({ id }) => id).join(", ")}`);
+    }
+    if (summary.blocking.length > 0) {
+        lines.push(`- residual blocking P1/P2: ${summary.blocking.map(({ id }) => id).join(", ")}`);
+    }
+    else {
+        lines.push("- residual blocking P1/P2: none");
+    }
+    return lines.join("\n");
+}
+/**
+ * Fallback gate-evidence reuse (Issue 08 artifacts are optional): a completed
+ * Task-final Round whose evidence commit exactly matches the candidate's
+ * primary head may donate its checks by digest.  A changed head returns null,
+ * so an old GREEN can never be reused against a different tree.
+ */
+export function reusableTaskReviewEvidence(store, taskId, candidate) {
+    const rounds = store.listReviewRounds(taskId)
+        .filter((round) => (round.scope ?? "work-item") === "task"
+        && round.status === "completed"
+        && round.evidenceCommit !== undefined
+        && isSameTaskReviewCandidate(round.taskCandidate, candidate))
+        .sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true }));
+    const latest = rounds.at(-1);
+    if (latest === undefined || latest.evidenceCommit === undefined)
+        return null;
+    const checks = latest.checks ?? [];
+    if (checks.length === 0 || checks.some((check) => check.outcome !== "passed"))
+        return null;
+    const digest = createHash("sha256")
+        .update(JSON.stringify(checks))
+        .digest("hex");
+    return {
+        reviewRoundId: latest.id,
+        evidenceCommit: latest.evidenceCommit,
+        digest,
+        checks
+    };
+}
+/**
+ * Builds the Issue 06 incremental Review context. The Reviewer receives the
+ * cross-Round ledger, exact old/new frozen heads, repair evidence, and any
+ * reusable exact-head checks. A changed head or failed/absent checks returns
+ * no reusable evidence, so an old GREEN can never be borrowed for a new tree.
+ */
+export function buildTaskFinalReviewFindingContext(store, taskId, candidate) {
+    const previousSemanticRound = store.listReviewRounds(taskId)
+        .filter((round) => (round.scope ?? "work-item") === "task" && round.status === "completed")
+        .sort((left, right) => left.id.localeCompare(right.id, undefined, { numeric: true }))
+        .at(-1) ?? null;
+    const reusableEvidence = reusableTaskReviewEvidence(store, taskId, candidate);
+    // dbonly: the finding ledger is SQLite-native.  A file-only Home (no yui.db)
+    // cannot serve findings; the Review dispatch must still proceed, so the
+    // ledger context degrades to an explicit "unavailable" note.
+    let ledgerContext;
+    try {
+        ledgerContext = renderFindingLedgerContext(summarizeFindingLedger(store, taskId));
+    }
+    catch {
+        ledgerContext = "Finding ledger: unavailable (SQLite backend required; run `yui update` to migrate this Home).";
+    }
+    const lines = [
+        "Review convergence context:",
+        ledgerContext,
+        ...(previousSemanticRound === null
+            ? ["Previous semantic Task-final ReviewRound: none."]
+            : [
+                `Previous semantic Task-final ReviewRound: ${previousSemanticRound.id}`,
+                ...candidate.projects.map((project) => {
+                    const previous = previousSemanticRound.taskCandidate?.projects
+                        .find((entry) => entry.projectId === project.projectId)?.commit;
+                    return previous === undefined
+                        ? `Exact review boundary for ${project.projectId}: new head ${project.commit}`
+                        : previous === project.commit
+                            ? `Exact review boundary for ${project.projectId}: unchanged at ${project.commit}`
+                            : `Exact diff for ${project.projectId}: ${previous}..${project.commit}`;
+                })
+            ]),
+        ...(reusableEvidence === null
+            ? [
+                "Reusable gate evidence: none (head changed, checks are absent, or a check did not pass); rerun the checks needed for this exact tree."
+            ]
+            : [
+                `Reusable gate evidence: ${reusableEvidence.reviewRoundId}@${reusableEvidence.evidenceCommit}`,
+                `Reusable check digest: ${reusableEvidence.digest}`,
+                `Reusable checks: ${reusableEvidence.checks.map(({ name, outcome }) => `${name}=${outcome}`).join(", ")}`
+            ]),
+        "Reuse each listed ledger finding id when it is still valid; explain why a new finding is not already covered by the ledger.",
+        "Your final report must clearly list verified-fixed findings, new findings, accepted risks, and residual verification gaps."
+    ];
+    return {
+        context: lines.join("\n"),
+        previousSemanticRound,
+        reusableEvidence
+    };
+}
+function isSameTaskReviewCandidate(left, right) {
+    return left !== undefined
+        && left.projects.length === right.projects.length
+        && left.projects.every((project, index) => (project.projectId === right.projects[index]?.projectId
+            && project.commit === right.projects[index]?.commit));
+}

package/dist/review/reviewOutcomeClassifier.js

@@ -0,0 +1,61 @@
+const INFRA_SIGNATURES = [
+    {
+        kind: "session-not-stopped",
+        pattern: /session must be stopped before workspace migration/iu
+    },
+    {
+        kind: "run-start",
+        pattern: /role run could not start|could not start (?:the )?(?:reviewer|role) run/iu
+    },
+    {
+        kind: "storage-lock",
+        pattern: /\.state\.lock|state lock|lock timeout|storage lock/iu
+    },
+    {
+        kind: "tmux-exit",
+        pattern: /tmux[^\n]{0,80}(?:exited|exit|died|vanished)|pane (?:exited|died)/iu
+    },
+    {
+        kind: "yield-timeout",
+        pattern: /yield timeout|controller yield timeout|yield timed out/iu
+    },
+    {
+        kind: "run-identity",
+        pattern: /wrong run id|unknown run id|run id (?:is )?(?:invalid|unknown|mismatch)/iu
+    },
+    {
+        kind: "policy",
+        pattern: /cyber_?policy|policy denial|permission denied by policy/iu
+    },
+    {
+        kind: "baseline-contamination",
+        pattern: /cross[-\s]?baseline|baseline pollution|contaminated baseline|wrong base sha/iu
+    }
+];
+/**
+ * Classifies a terminal Round.  `completed` is always semantic (the reviewer
+ * delivered a report); `failed` is always infra.  Non-terminal Rounds have no
+ * outcome yet.
+ */
+export function classifyReviewRoundOutcome(round) {
+    if (round.status === "completed") {
+        return { kind: "semantic", reason: "Reviewer delivered a report." };
+    }
+    if (round.status !== "failed")
+        return null;
+    const text = `${round.summary ?? ""}\n${round.report ?? ""}`;
+    for (const { kind, pattern } of INFRA_SIGNATURES) {
+        if (pattern.test(text)) {
+            return { kind: "infra", infraKind: kind, reason: `Review execution attempt failed (${kind}).` };
+        }
+    }
+    return {
+        kind: "infra",
+        infraKind: "other-infra",
+        reason: "Review execution attempt failed before a semantic report."
+    };
+}
+/** True when this Round may feed the finding ledger. */
+export function isSemanticReviewRound(round) {
+    return classifyReviewRoundOutcome(round)?.kind === "semantic";
+}

package/dist/review/reviewRound.js

@@ -2,7 +2,7 @@ import { requireIdentity, requireText, requireTimestamp } from "../domain/valida
 import { validateTaskRecordReference } from "../task/taskRecordReference.js";
 import { validateTaskFinalReviewContract } from "./taskFinalReviewContract.js";
 import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
-import { assertExecutionGroupTransition, validateExecutionGroup } from "../execution/executionGroup.js";
+import { assertExecutionGroupTransition, resetReviewExecutionLane, validateExecutionGroup } from "../execution/executionGroup.js";
 export function createReviewRound(id, taskId, workItemId, candidateId, reviewerRoleName, requestedBy, reviewBaseCommit, now, executionGroup) {
     return validateReviewRound({
         schemaVersion: 4,
@@ -84,6 +84,56 @@ export function finishReviewRound(round, status, summary, now, result = {}) {
         endedAt: now.toISOString()
     });
 }
+/**
+ * Issue 06: retry a failed Task-final execution attempt under the same semantic
+ * Round identity. AgentRun history remains the attempt trail; the Round itself
+ * returns to pending so infrastructure retries do not manufacture a new
+ * semantic ReviewRound or duplicate findings.
+ */
+export function retryTaskReviewRound(round) {
+    validateReviewRound(round);
+    if ((round.scope ?? "work-item") !== "task") {
+        throw new Error(`Only a Task-final ReviewRound can be retried in place: ${round.id}.`);
+    }
+    if (round.status !== "failed") {
+        throw new Error(`ReviewRound ${round.id} is not retryable from ${round.status}.`);
+    }
+    const retryExecutionGroup = round.executionGroup === undefined
+        ? undefined
+        : retryReviewExecutionGroup(round);
+    return validateReviewRound({
+        schemaVersion: round.schemaVersion,
+        id: round.id,
+        taskId: round.taskId,
+        workItemId: round.workItemId,
+        candidateId: round.candidateId,
+        reviewerRoleName: round.reviewerRoleName,
+        reviewBaseCommit: round.reviewBaseCommit,
+        scope: "task",
+        ...(round.taskCandidate === undefined ? {} : { taskCandidate: round.taskCandidate }),
+        ...(round.taskFinalReviewContract === undefined
+            ? {}
+            : { taskFinalReviewContract: round.taskFinalReviewContract }),
+        // Keep the historical attempt Group and Lane addressable from AgentRun
+        // history while resetting the Lane for another dispatch attempt.
+        ...(retryExecutionGroup === undefined ? {} : { executionGroup: retryExecutionGroup }),
+        requestedBy: "leader",
+        status: "pending",
+        ...(round.workspace === undefined ? {} : { workspace: round.workspace }),
+        createdAt: round.createdAt
+    });
+}
+function retryReviewExecutionGroup(round) {
+    const previous = round.executionGroup;
+    const attemptTime = Date.parse(round.endedAt ?? round.createdAt);
+    const now = new Date(attemptTime);
+    const lanes = previous.lanes.map((lane) => (resetReviewExecutionLane(previous, lane.id, now)));
+    return validateExecutionGroup({
+        ...previous,
+        lanes,
+        updatedAt: now.toISOString()
+    });
+}
 /** Accepts the Reviewer's complete report and extracts only optional known evidence. */
 export function parseReviewYieldReport(value) {
     const report = requireText(value, "Review report");
@@ -265,10 +315,12 @@ export function validateReviewRound(round) {
         requireText(round.report ?? "", "Review report");
         validateChecks(round.checks ?? []);
         if (round.evidenceCommit !== undefined) {
+            // The exact commit on which the review's checks ran.  Equals the base
+            // when the reviewer ran checks on the frozen candidate tree; differs
+            // when the reviewer committed diagnostics on top of it.  A dirty
+            // review with uncommitted changes records no evidenceCommit, since no
+            // single commit captures the checked tree.
             requireCommit(round.evidenceCommit, "Review evidence commit");
-            if (round.evidenceCommit === round.reviewBaseCommit) {
-                throw new Error("Review evidence commit must differ from its review base.");
-            }
         }
         requireTimestamp(round.endedAt ?? "", "ReviewRound endedAt");
     }