@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/dist/lib/task/qualification-intents.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import { CONSTRAINT_COLUMNS, CANDIDATE_COLUMNS, parseTaskQualification } from './qualification-audit.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { captureTaskWriteMetadata, writeTask } from './write.js';
+function failed(code, message, taskId = null) {
+    return { status: 'failed', changed: false, taskId, operations: [], error: { code, message } };
+}
+function validSingleLine(value) {
+    return typeof value === 'string' && Boolean(value.trim()) && !/[\r\n]/.test(value);
+}
+function assertProposalKeys(value, keys, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${label} must be an object`);
+    const record = value;
+    const unexpected = Object.keys(record).find((key) => !keys.includes(key));
+    if (unexpected)
+        throw new Error(`${label} does not accept '${unexpected}'`);
+    return record;
+}
+function parseConstraintProposal(value) {
+    const row = assertProposalKeys(value, ['constraintId', 'statement', 'status', 'authority', 'source', 'evidence', 'derivedFrom', 'approvalEvidence'], 'constraint proposal');
+    for (const key of ['constraintId', 'statement', 'status', 'authority', 'source', 'evidence', 'approvalEvidence']) {
+        if (typeof row[key] !== 'string' || /[\r\n]/.test(row[key]))
+            throw new Error(`constraint proposal '${key}' must be a single-line string`);
+    }
+    if (!/^C-[1-9]\d*$/.test(row.constraintId))
+        throw new Error(`constraint proposal id '${row.constraintId}' is invalid`);
+    if (row.status === 'confirmed' || !['derived', 'assumption', 'open', 'conflicted', 'superseded'].includes(row.status))
+        throw new Error('proposal cannot write confirmed constraint status');
+    if (row.approvalEvidence !== '')
+        throw new Error('proposal cannot write approval_evidence');
+    if (!Array.isArray(row.derivedFrom) || row.derivedFrom.some((item) => typeof item !== 'string' || !/^C-[1-9]\d*$/.test(item)))
+        throw new Error('constraint proposal derivedFrom is invalid');
+    return {
+        constraintId: row.constraintId, statement: row.statement, status: row.status,
+        authority: row.authority, source: row.source, evidence: row.evidence,
+        derivedFrom: [...row.derivedFrom], approvalEvidence: ''
+    };
+}
+function parseCandidateProposal(value) {
+    const row = assertProposalKeys(value, ['candidateId', 'statement', 'status', 'constraintIds', 'impact', 'evidence'], 'candidate proposal');
+    for (const key of ['candidateId', 'statement', 'status', 'impact', 'evidence'])
+        if (!validSingleLine(row[key]))
+            throw new Error(`candidate proposal '${key}' must be a non-empty single-line string`);
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(row.candidateId))
+        throw new Error(`candidate proposal id '${row.candidateId}' is invalid`);
+    if (row.status !== 'pending')
+        throw new Error('proposal can only write pending candidate status');
+    if (!Array.isArray(row.constraintIds) || row.constraintIds.some((item) => typeof item !== 'string' || !/^C-[1-9]\d*$/.test(item)))
+        throw new Error('candidate proposal constraintIds is invalid');
+    return row;
+}
+function proposalValues(request) {
+    if (!/^[a-f0-9]{64}$/i.test(request.expectedTaskInputDigest))
+        throw new Error('expectedTaskInputDigest must be a sha256 digest');
+    if (Object.keys(request).some((key) => !['taskRef', 'expectedTaskInputDigest', 'constraints', 'candidates', 'dryRun'].includes(key)))
+        throw new Error('proposal contains an unsupported field');
+    if (!Array.isArray(request.constraints) && request.constraints !== undefined)
+        throw new Error('constraints must be an array');
+    if (!Array.isArray(request.candidates) && request.candidates !== undefined)
+        throw new Error('candidates must be an array');
+    return {
+        constraints: (request.constraints ?? []).map(parseConstraintProposal),
+        candidates: (request.candidates ?? []).map(parseCandidateProposal)
+    };
+}
+function applyQualificationProposal(request, options = {}) {
+    if (!request || typeof request !== 'object' || !validSingleLine(request.taskRef))
+        return failed('QUALIFICATION_PROPOSAL_INVALID', 'taskRef is required');
+    let values;
+    try {
+        values = proposalValues(request);
+    }
+    catch (error) {
+        return failed('QUALIFICATION_PROPOSAL_INVALID', error instanceof Error ? error.message : String(error));
+    }
+    if (values.constraints.length === 0 && values.candidates.length === 0)
+        return failed('QUALIFICATION_PROPOSAL_INVALID', 'proposal must contain a constraint or candidate');
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(resolved.code, resolved.message, resolved.taskId);
+    if (resolved.state !== 'active')
+        return failed('TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+    let content;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    }
+    catch (error) {
+        return failed('TASK_READ_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    const parsed = parseTaskQualification(content);
+    if (!parsed.ok)
+        return failed(parsed.code, parsed.message, resolved.taskId);
+    if (!parsed.qualification.present)
+        return failed('QUALIFICATION_TASK_CONTRACT_MISSING', 'task qualification contract is missing', resolved.taskId);
+    const currentConstraintMap = new Map(parsed.qualification.constraints.map((row) => [row.constraintId, row]));
+    const currentCandidateMap = new Map(parsed.qualification.candidates.map((row) => [row.candidateId, row]));
+    const proposalAlreadyApplied = values.constraints.every((row) => {
+        const current = currentConstraintMap.get(row.constraintId);
+        return current && current.statement === row.statement && current.status === row.status && current.authority === row.authority
+            && current.source === row.source && current.evidence === row.evidence && current.derivedFrom.join(',') === row.derivedFrom.join(',') && current.approvalEvidence === '';
+    }) && values.candidates.every((row) => {
+        const current = currentCandidateMap.get(row.candidateId);
+        return current && current.statement === row.statement && current.status === row.status && current.constraintIds.join(',') === row.constraintIds.join(',')
+            && current.impact === row.impact && current.evidence === row.evidence;
+    });
+    if (parsed.qualification.taskInputDigest !== request.expectedTaskInputDigest) {
+        return proposalAlreadyApplied
+            ? { status: 'no-op', changed: false, taskId: resolved.taskId, operations: [], error: null }
+            : failed('QUALIFICATION_DIGEST_CONFLICT', 'task qualification input changed before proposal was applied', resolved.taskId);
+    }
+    for (const row of values.constraints) {
+        const current = currentConstraintMap.get(row.constraintId);
+        if (current?.status === 'confirmed')
+            return failed('QUALIFICATION_CONFIRMATION_REQUIRED', `confirmed constraint '${row.constraintId}' must be superseded or revoked through task-qualification`, resolved.taskId);
+    }
+    const knownConstraintIds = new Set([...parsed.qualification.constraints.map((row) => row.constraintId), ...values.constraints.map((row) => row.constraintId)]);
+    for (const row of values.constraints)
+        for (const parent of row.derivedFrom)
+            if (!knownConstraintIds.has(parent))
+                return failed('QUALIFICATION_CONSTRAINT_UNKNOWN', `constraint proposal '${row.constraintId}' references unknown '${parent}'`, resolved.taskId);
+    for (const row of values.candidates)
+        for (const id of row.constraintIds)
+            if (!knownConstraintIds.has(id))
+                return failed('QUALIFICATION_CONSTRAINT_UNKNOWN', `candidate proposal '${row.candidateId}' references unknown '${id}'`, resolved.taskId);
+    const mutations = [];
+    for (const row of values.constraints) {
+        mutations.push({ kind: 'table-row', action: 'upsert', sectionAliases: ['约束', 'Constraints'], columns: CONSTRAINT_COLUMNS, keyColumn: 'constraint_id', key: row.constraintId, values: { statement: row.statement, status: row.status, authority: row.authority, source: row.source, evidence: row.evidence, derived_from: row.derivedFrom.join(','), approval_evidence: '' } });
+    }
+    for (const row of values.candidates) {
+        mutations.push({ kind: 'table-row', action: 'upsert', sectionAliases: ['候选与否决方案', 'Candidate and Rejected Options', 'Candidates and Rejected Options', 'Candidates and Rejected Alternatives'], columns: CANDIDATE_COLUMNS, keyColumn: 'candidate_id', key: row.candidateId, values: { statement: row.statement, status: row.status, constraint_ids: row.constraintIds.join(','), impact: row.impact, evidence: row.evidence } });
+    }
+    // Only the submitted rows are mutated; no actor, confirmation, or QCR fields
+    // can be smuggled into this internal proposal operation.
+    let metadata;
+    try {
+        metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+    }
+    catch (error) {
+        return failed('METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
+    }
+    const result = writeTask({ taskRef: resolved.taskId, expectedState: 'active', mutations, dryRun: request.dryRun }, { ...options, taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state }, metadataProvider: () => metadata });
+    if (result.status === 'failed')
+        return failed(result.error.code, result.error.message, result.taskId);
+    return { status: result.status, changed: result.changed, taskId: result.taskId, operations: result.operations, error: null };
+}
+export { applyQualificationProposal };
+//# sourceMappingURL=qualification-intents.js.map

package/dist/lib/task/review-artifacts.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { scanVisibleMarkdown } from './markdown.js';
 const SUMMARY_HEADINGS = new Set(['审查摘要', 'Review Summary']);
 const PLACEHOLDERS = [
     '{unresolved-blockers}',
@@ -9,22 +10,6 @@ const PLACEHOLDERS = [
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function maxRound(entries, stem) {
-    let max = 0;
-    for (const entry of entries) {
-        if (entry === `${stem}.md`) {
-            max = Math.max(max, 1);
-            continue;
-        }
-        const match = entry.match(new RegExp(`^${escapeRegExp(stem)}-r(\\d+)\\.md$`));
-        if (match)
-            max = Math.max(max, Number(match[1]));
-    }
-    return max;
-}
-function artifactName(stem, round) {
-    return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
-}
 function normalizeVerdict(raw) {
     const value = String(raw).trim().toLowerCase();
     if (value === '通过' || value === 'approved')
@@ -36,42 +21,40 @@ function normalizeVerdict(raw) {
     return '';
 }
 function extractSection(content, names) {
-    const lines = content.split(/\r?\n/);
     const nameSet = new Set(names);
-    const start = lines.findIndex((line) => {
-        const match = line.trim().match(/^##\s+(.+?)\s*$/);
-        return match ? nameSet.has(match[1]) : false;
-    });
-    if (start === -1)
+    const scanned = scanVisibleMarkdown(content);
+    const heading = scanned.headings.find((item) => item.level === 2 && nameSet.has(item.text));
+    if (!heading)
         return '';
-    const sectionLines = [];
-    for (let index = start + 1; index < lines.length; index += 1) {
-        if (/^##\s+/.test(lines[index]))
-            break;
-        sectionLines.push(lines[index]);
-    }
-    return sectionLines.join('\n');
+    const next = scanned.headings.find((item) => item.start > heading.start && item.level <= 2);
+    return content.slice(heading.end, next?.start ?? content.length);
 }
 function summaryBounds(content) {
-    const headings = [...content.matchAll(/^##\s+(.+?)\s*$/gm)]
-        .map((match) => ({ index: match.index, end: match.index + match[0].length, name: match[1] }));
-    const summaries = headings.filter((heading) => SUMMARY_HEADINGS.has(heading.name));
+    const scanned = scanVisibleMarkdown(content);
+    const summaries = scanned.headings.filter((heading) => heading.level === 2 && SUMMARY_HEADINGS.has(heading.text));
     if (summaries.length !== 1)
         return null;
     const summary = summaries[0];
-    const next = headings.find((heading) => heading.index > summary.index);
-    return { start: summary.end, end: next?.index ?? content.length };
+    const next = scanned.headings.find((heading) => heading.start > summary.start && heading.level <= 2);
+    return { start: summary.end, end: next?.start ?? content.length };
 }
 function uniqueLine(content, bounds, pattern) {
-    const section = content.slice(bounds.start, bounds.end);
-    const matches = [...section.matchAll(pattern)];
+    const matches = [];
+    for (const line of scanVisibleMarkdown(content).lines) {
+        if (line.start < bounds.start || line.start >= bounds.end)
+            continue;
+        pattern.lastIndex = 0;
+        const match = pattern.exec(line.text);
+        if (match)
+            matches.push({ value: match[1], index: line.start + match.index, length: match[0].length });
+    }
     if (matches.length !== 1)
         return null;
     const match = matches[0];
     return {
-        value: match[1],
-        start: bounds.start + match.index,
-        end: bounds.start + match.index + match[0].length
+        value: match.value,
+        start: match.index,
+        end: match.index + match.length
     };
 }
 function parseCounts(value) {
@@ -200,5 +183,5 @@ function parseVerdict(reviewPath) {
     }
     return resolveCanonicalVerdict(parsed.summary);
 }
-export { artifactName, equalCounts, escapeRegExp, extractSection, finalizeReviewSummaryContent, maxRound, normalizeVerdict, parseReviewSummary, parseVerdict, resolveCanonicalVerdict };
+export { equalCounts, escapeRegExp, extractSection, finalizeReviewSummaryContent, normalizeVerdict, parseReviewSummary, parseVerdict, resolveCanonicalVerdict };
 //# sourceMappingURL=review-artifacts.js.map

package/dist/lib/task/review-command.js

@@ -0,0 +1,25 @@
+export function parseReviewCommand(args) {
+    if (!args[0] || args[1] !== 'finalize-summary')
+        throw new Error('task ref and finalize-summary are required');
+    const values = {};
+    const flags = {
+        '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',
+        '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
+    };
+    for (let index = 2; index < args.length; index += 1) {
+        const flag = args[index];
+        if (!Object.hasOwn(flags, flag))
+            throw new Error(`unknown option '${flag}'`);
+        const key = flags[flag];
+        if (Object.hasOwn(values, key))
+            throw new Error(`duplicate option '${flag}'`);
+        const value = flag === '--orchestrated' || flag === '--dry-run' ? true : args[++index];
+        if (!value || typeof value === 'string' && value.startsWith('--'))
+            throw new Error(`option '${flag}' requires a value`);
+        values[key] = value;
+    }
+    if (!values.stage || !values.artifact)
+        throw new Error("options '--stage' and '--artifact' are required");
+    return { taskRef: args[0], ...values };
+}
+//# sourceMappingURL=review-command.js.map

package/dist/lib/task/review-finalization.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.js';
-import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.js';
+import { parseArtifactName } from './artifact-name.js';
+import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { inspectDecisionDetailDuplicates } from './decision-details.js';
@@ -10,10 +10,13 @@ import { resolveTaskRef } from './resolve-ref.js';
 import { validateLifecycleExecution } from './lifecycle-execution.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { allowsManualOverride } from './guard-override.js';
+import { getArtifactSchema } from './artifact-schema.js';
+import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.js';
+import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.js';
 const STAGES = {
-    analysis: { family: 'review-analysis', action: 'Review Analysis' },
-    plan: { family: 'review-plan', action: 'Review Plan' },
-    code: { family: 'review-code', action: 'Review Code' }
+    analysis: { family: 'review-analysis' },
+    plan: { family: 'review-plan' },
+    code: { family: 'review-code' }
 };
 const DEFAULT_FILE_SYSTEM = {
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
@@ -22,7 +25,7 @@ const DEFAULT_FILE_SYSTEM = {
     renameSync: (from, to) => fs.renameSync(from, to),
     unlinkSync: (file) => fs.unlinkSync(file)
 };
-function failed(request, code, message, taskId = null, stageStatus = null) {
+function failed(request, code, message, taskId = null, stageStatus = null, extra = {}) {
     return {
         status: 'failed',
         changed: false,
@@ -32,17 +35,15 @@ function failed(request, code, message, taskId = null, stageStatus = null) {
         stage: request.stage,
         artifact: request.artifact,
         stageStatus,
+        artifactSha256: null,
+        semanticDigest: null,
+        repairable: false,
+        operation: null,
         operations: [],
-        error: { code, message }
+        error: { code, message },
+        ...extra
     };
 }
-function openReviewRound(content, action, round) {
-    const section = locateActivityLog(content);
-    if (!section)
-        return false;
-    const expected = `${action} (Round ${round})`;
-    return startedBackedRows(pairEntries(section.entries)).filter((row) => (row.step === expected && !row.done)).length === 1;
-}
 function cleanupTemp(fileSystem, tempPath) {
     try {
         fileSystem.unlinkSync(tempPath);
@@ -51,131 +52,179 @@ function cleanupTemp(fileSystem, tempPath) {
         // Best-effort cleanup preserves the primary failure.
     }
 }
-function finalizeReviewSummaryUnlocked(request, options = {}) {
+/** Prepare domain validation, summary bytes and provenance before any publication. */
+function prepareReviewSummaryCandidate(request, artifactContent, options = {}) {
+    let taskId = null;
+    let stageStatus = null;
+    const reject = (code, message, extra = {}) => ({
+        result: failed(request, code, message, taskId, stageStatus, extra), content: artifactContent
+    });
     const stage = request.stage;
     const spec = STAGES[stage];
     if (!spec)
-        return failed(request, 'REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
-    if (!request.taskRef || !request.artifact) {
-        return failed(request, 'REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
-    }
+        return reject('REVIEW_STAGE_INVALID', `unsupported review stage '${request.stage}'`);
+    if (!request.taskRef || !request.artifact)
+        return reject('REVIEW_PAYLOAD_INVALID', 'taskRef, stage, and artifact are required');
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    taskId = resolved.taskId ?? null;
     if (!resolved.ok)
-        return failed(request, resolved.code, resolved.message, resolved.taskId);
+        return reject(resolved.code, resolved.message);
     if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
-        return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
-    }
-    const parsedArtifact = parseArtifactName(request.artifact);
-    if (!parsedArtifact || parsedArtifact.family !== spec.family) {
-        return failed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`, resolved.taskId);
+        return reject('TASK_STATE_MISMATCH', `task ${taskId} is ${resolved.state}, expected active`);
+    }
+    const parsed = parseArtifactName(request.artifact);
+    if (!parsed || parsed.family !== spec.family)
+        return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `artifact '${request.artifact}' does not match ${spec.family}`);
+    const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
+    if (publicationError)
+        return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message);
+    let taskContent;
+    try {
+        taskContent = (options.fileSystem?.readFileSync ?? DEFAULT_FILE_SYSTEM.readFileSync)(resolved.taskMdPath);
     }
-    const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact, parsedArtifact.round);
-    if (!validated.ok) {
-        const code = validated.error.code === 'ARTIFACT_NOT_REGULAR'
-            ? 'REVIEW_ARTIFACT_NOT_REGULAR'
-            : 'REVIEW_ARTIFACT_IDENTITY_INVALID';
-        return failed(request, code, validated.error.message, resolved.taskId);
+    catch (error) {
+        return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error));
     }
-    const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
-    let taskContent;
-    let artifactContent;
+    const artifactSha256 = sha256Content(artifactContent);
+    const semanticDigest = canonicalSemanticDigest(artifactContent);
+    const digests = { artifactSha256, semanticDigest };
+    let repairIntent;
     try {
-        taskContent = fileSystem.readFileSync(resolved.taskMdPath);
-        artifactContent = fileSystem.readFileSync(validated.artifact.path);
+        repairIntent = readArtifactRepairIntent(resolved.repoRoot, taskId, spec.family, request.artifact);
     }
     catch (error) {
-        return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+        return reject('REVIEW_PROVENANCE_INVALID', String(error), digests);
+    }
+    const schema = getArtifactSchema(spec.family);
+    const structure = inspectArtifactContract(artifactContent, schema);
+    if (!structure.ok) {
+        const repairable = structure.repair !== null && structure.diagnostics.length === 1 && structure.diagnostics[0]?.repairable === true;
+        if (repairable && repairIntent && (repairIntent.state !== 'awaiting-repair'
+            || repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== structure.semanticDigest)) {
+            return reject('REVIEW_PROVENANCE_INVALID', 'a different review repair baseline is already recorded for this artifact', digests);
+        }
+        return {
+            ...reject('REVIEW_ARTIFACT_STRUCTURE_INVALID', structure.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; '), {
+                artifactSha256, semanticDigest: structure.semanticDigest, repairable, operation: structure.repair
+            }),
+            ...(repairable && !repairIntent ? { provenance: {
+                    version: 2, taskId: taskId, family: spec.family, artifact: request.artifact,
+                    state: 'awaiting-repair', baselineSemanticDigest: structure.semanticDigest,
+                    artifactSha256, semanticDigest: structure.semanticDigest,
+                    recoveryOperationId: null, phase: null, authorityDigest: null,
+                    requestId: `review-finalize:${taskId}`, createdAt: Date.now(), updatedAt: Date.now()
+                }, expectedIntent: null } : {})
+        };
+    }
+    if (repairIntent?.state === 'awaiting-repair' && repairIntent.baselineSemanticDigest !== semanticDigest) {
+        return reject('REVIEW_PROVENANCE_INVALID', 'the repaired review artifact semantic digest does not match the recorded repair baseline', digests);
+    }
+    if ((repairIntent?.state === 'passed' || repairIntent?.state === 'consumed')
+        && (repairIntent.artifactSha256 !== artifactSha256 || repairIntent.semanticDigest !== semanticDigest)) {
+        return reject('REVIEW_PROVENANCE_INVALID', 'the review artifact changed after its finalization provenance was recorded', digests);
     }
-    if (!openReviewRound(taskContent, spec.action, parsedArtifact.round)) {
-        return failed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`, resolved.taskId);
+    if (!hasOpenArtifactRound(taskContent, spec.family, parsed.round)) {
+        return reject('REVIEW_ARTIFACT_IDENTITY_INVALID', `${request.artifact} does not have one matching open started review event`);
     }
     const execution = validateLifecycleExecution(request.taskRef, {
         mode: request.orchestrated ? 'orchestrated' : 'standalone',
-        identity: {
-            stage: spec.family,
-            round: parsedArtifact.round,
-            artifact: request.artifact,
-            role: 'reviewer'
-        },
+        identity: { stage: spec.family, round: parsed.round, artifact: request.artifact, role: 'reviewer' },
         dryRun: request.dryRun
     }, { repoRoot: options.repoRoot });
     if (!execution.ok) {
-        return failed(request, 'REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`, resolved.taskId);
+        return reject('REVIEW_PROVENANCE_INVALID', `${execution.error?.code ?? 'ORCHESTRATION_PROVENANCE_MISMATCH'}: ${execution.error?.message ?? 'orchestration provenance validation failed'}`);
     }
-    let rows;
     try {
         const ledger = parseLedgerDocument(taskContent);
-        if (!ledger.present) {
-            return failed(request, 'REVIEW_LEDGER_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`, resolved.taskId);
-        }
-        rows = ledger.rows;
+        if (!ledger.present)
+            return reject('REVIEW_LEDGER_INVALID', `${LEDGER_SECTION_MISSING_CODE}: ${LEDGER_SECTION_MISSING_MESSAGE}`);
+        const error = validateLedgerRows(ledger.rows);
+        if (error)
+            return reject('REVIEW_LEDGER_INVALID', `${error.code}: ${error.message}`);
+        stageStatus = summarizeLedgerStage(ledger.rows, stage);
     }
     catch (error) {
-        return failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
+        return reject('REVIEW_LEDGER_INVALID', String(error));
     }
-    const ledgerError = validateLedgerRows(rows);
-    if (ledgerError) {
-        return failed(request, 'REVIEW_LEDGER_INVALID', `${ledgerError.code}: ${ledgerError.message}`, resolved.taskId);
+    const detail = inspectDecisionDetailDuplicates(artifactContent);
+    if (!detail.ok)
+        return reject('REVIEW_DECISION_DETAIL_INVALID', `${detail.code}: ${detail.message}`);
+    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
+    if (!transformed.ok)
+        return reject(transformed.code, transformed.message);
+    const finalDigests = { artifactSha256: sha256Content(transformed.content), semanticDigest: canonicalSemanticDigest(transformed.content) };
+    return {
+        content: transformed.content,
+        result: {
+            ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', taskId, stageStatus, finalDigests),
+            status: transformed.changed ? request.dryRun ? 'planned' : 'applied' : 'no-op',
+            changed: transformed.changed,
+            operations: transformed.changed ? [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }] : [],
+            error: null
+        },
+        ...(repairIntent?.state === 'awaiting-repair' ? {
+            provenance: { ...repairIntent, state: 'passed', ...finalDigests },
+            expectedIntent: repairIntent
+        } : {})
+    };
+}
+function commitReviewSummaryProvenance(prepared, repoRoot) {
+    try {
+        if (prepared.provenance) {
+            writeArtifactRepairIntent(repoRoot, prepared.provenance, { expected: prepared.expectedIntent ?? null });
+        }
+        return prepared.result;
     }
-    const stageStatus = summarizeLedgerStage(rows, stage);
-    const detailInspection = inspectDecisionDetailDuplicates(artifactContent);
-    if (!detailInspection.ok) {
-        return failed(request, 'REVIEW_DECISION_DETAIL_INVALID', `${detailInspection.code}: ${detailInspection.message}`, resolved.taskId, stageStatus);
+    catch (error) {
+        return { ...prepared.result, status: 'failed', error: {
+                code: 'REVIEW_PROVENANCE_INVALID', message: `cannot record review provenance: ${String(error)}`
+            } };
     }
-    const transformed = finalizeReviewSummaryContent(artifactContent, stageStatus.unresolvedFindingCounts);
-    if (!transformed.ok) {
-        return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
+}
+function finalizeReviewSummaryUnlocked(request, options = {}) {
+    const spec = STAGES[request.stage];
+    if (!spec || !request.taskRef || !request.artifact)
+        return prepareReviewSummaryCandidate(request, '', options).result;
+    const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return failed(request, resolved.code, resolved.message, resolved.taskId);
+    const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
+    if (!validated.ok) {
+        return failed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
     }
-    if (!transformed.changed) {
-        return {
-            ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
-            status: 'no-op',
-            error: null
-        };
+    const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+    let content;
+    try {
+        content = fileSystem.readFileSync(validated.artifact.path);
     }
-    const operations = [{ kind: 'artifact', artifact: request.artifact, operation: 'update' }];
-    if (request.dryRun) {
-        return {
-            ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
-            status: 'planned',
-            changed: true,
-            operations,
-            error: null
-        };
+    catch (error) {
+        return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
     }
+    const prepared = prepareReviewSummaryCandidate(request, content, options);
+    if (request.dryRun)
+        return prepared.result;
+    if (prepared.result.status !== 'applied')
+        return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
     const tempPath = path.join(resolved.taskDir, `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`);
-    let mode;
     try {
-        mode = fileSystem.statModeSync(validated.artifact.path);
-        fileSystem.writeFileSync(tempPath, transformed.content, mode);
+        fileSystem.writeFileSync(tempPath, prepared.content, fileSystem.statModeSync(validated.artifact.path));
     }
     catch (error) {
         cleanupTemp(fileSystem, tempPath);
-        return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, stageStatus);
+        return failed(request, 'REVIEW_TEMP_WRITE_FAILED', String(error), resolved.taskId, prepared.result.stageStatus);
     }
     try {
-        if (fileSystem.readFileSync(validated.artifact.path) !== artifactContent) {
+        if (fileSystem.readFileSync(validated.artifact.path) !== content) {
             cleanupTemp(fileSystem, tempPath);
-            return failed(request, 'REVIEW_ARTIFACT_CONFLICT', `${request.artifact} changed during finalization`, resolved.taskId, stageStatus);
+            return failed(request, 'REVIEW_ARTIFACT_CONFLICT', `${request.artifact} changed during finalization`, resolved.taskId, prepared.result.stageStatus);
         }
         fileSystem.renameSync(tempPath, validated.artifact.path);
     }
     catch (error) {
         cleanupTemp(fileSystem, tempPath);
-        return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, stageStatus);
+        return failed(request, 'REVIEW_RENAME_FAILED', String(error), resolved.taskId, prepared.result.stageStatus);
     }
-    return {
-        status: 'applied',
-        changed: true,
-        intent: 'finalize-summary',
-        requestRef: request.taskRef,
-        taskId: resolved.taskId,
-        stage,
-        artifact: request.artifact,
-        stageStatus,
-        operations,
-        error: null
-    };
+    return commitReviewSummaryProvenance(prepared, resolved.repoRoot);
 }
 function finalizeReviewSummary(request, options = {}) {
     if (request.dryRun || options.lockAlreadyHeld)
@@ -192,5 +241,5 @@ function finalizeReviewSummary(request, options = {}) {
         return failed(request, 'REVIEW_PROVENANCE_INVALID', `${error.code}: ${error.message}`, resolved.taskId);
     }
 }
-export { finalizeReviewSummary };
+export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 //# sourceMappingURL=review-finalization.js.map

package/dist/lib/task/review-fingerprint.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { artifactName, maxRound } from "./review-artifacts.js";
+import { artifactName, maxArtifactRound } from "./artifact-name.js";
 import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.js";
 const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
 export function parseReviewedGitTree(value) {
@@ -29,7 +29,7 @@ export function resolvePostReviewGlobs(config = {}, reviewConfig = {}) {
 }
 export function findAuthoritativeReviewCodeArtifact(taskDir) {
     const entries = fs.existsSync(taskDir) ? fs.readdirSync(taskDir) : [];
-    const round = maxRound(entries, "review-code");
+    const round = maxArtifactRound(entries, "review-code");
     if (round === 0) {
         return { ok: false, round: 0, fileName: null, path: null, error: null };
     }