@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/task/qualification-confirmation.ts

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+
+import { appendActivityEntry, locateActivityLog } from './activity-log.ts';
+import { CONFIRMATION_COLUMNS, CONFIRMATION_HEADINGS, constraintDigest, parseQualificationConfirmations, parseTaskQualification } from './qualification-audit.ts';
+import type { QualificationConfirmation } from './qualification-audit.ts';
+import { findSectionHeading } from './sections.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+type QualificationConfirmationRequest = {
+  taskRef: string;
+  constraintId: string;
+  expectedDigest: string;
+  rationale: string;
+  operation?: 'confirm' | 'supersede' | 'revoke';
+  dryRun?: boolean;
+};
+type QualificationConfirmationResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  taskId: string | null;
+  qcrId: string | null;
+  requestId: string | null;
+  operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+function failed(code: string, message: string, taskId: string | null = null): QualificationConfirmationResult {
+  return { status: 'failed', changed: false, taskId, qcrId: null, requestId: null, operations: [], error: { code, message } };
+}
+
+function nextQcrId(content: string): string {
+  let max = 0;
+  for (const match of content.matchAll(/^\|\s*(QCR-(\d+))\s*\|/gm)) max = Math.max(max, Number(match[2]));
+  return `QCR-${max + 1}`;
+}
+
+function requestIdFor(taskId: string, constraintId: string, expectedDigest: string, rationale: string, timestamp: string): string {
+  const hash = createHash('sha256').update(JSON.stringify([taskId, constraintId, expectedDigest, rationale, timestamp])).digest('hex');
+  return `QCR-REQUEST-${hash.slice(0, 20)}`;
+}
+
+function renderConfirmations(rows: readonly QualificationConfirmation[]): string {
+  return [
+    `| ${CONFIRMATION_COLUMNS.join(' | ')} |`,
+    `| ${CONFIRMATION_COLUMNS.map(() => '---').join(' | ')} |`,
+    ...rows.map((row) => [row.qcrId, row.constraintId, row.actor, row.entrypoint, row.requestId, row.approvedDigest, row.confirmedAt, row.rationale]
+      .map((value) => value.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/[\r\n]/g, ' '))
+      .join(' | ')).map((line) => `| ${line} |`)
+  ].join('\n');
+}
+
+function applyQualificationConfirmation(request: QualificationConfirmationRequest, options: TaskWriteOptions = {}): QualificationConfirmationResult {
+  if (!request || typeof request !== 'object' || !request.taskRef || !/^C-[1-9]\d*$/.test(request.constraintId) || !/^[a-f0-9]{64}$/i.test(request.expectedDigest) || !request.rationale?.trim() || /[\r\n]/.test(request.rationale)) {
+    return failed('QUALIFICATION_CONFIRMATION_INVALID', 'taskRef, constraintId, expectedDigest, and a single-line rationale are required');
+  }
+  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: string;
+  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 constraint = parsed.qualification.constraints.find((row) => row.constraintId === request.constraintId);
+  if (!constraint) return failed('QUALIFICATION_CONSTRAINT_UNKNOWN', `unknown constraint '${request.constraintId}'`, resolved.taskId);
+  const operation = request.operation ?? 'confirm';
+  const existing = parseQualificationConfirmations(content);
+  if (!existing.ok) return failed(existing.code, existing.message, resolved.taskId);
+  const previous = existing.confirmations.find((row) => row.qcrId === constraint.approvalEvidence);
+  if (operation === 'confirm' && constraint.status === 'confirmed') {
+    if (previous?.constraintId === constraint.constraintId && previous.approvedDigest === constraint.digest && previous.rationale === request.rationale.trim()) {
+      return { status: 'no-op', changed: false, taskId: resolved.taskId, qcrId: previous.qcrId, requestId: previous.requestId, operations: [], error: null };
+    }
+    return failed('QUALIFICATION_CONFIRMATION_CONFLICT', `constraint '${request.constraintId}' is already confirmed with different evidence`, resolved.taskId);
+  }
+  const transitionStatus = operation === 'supersede' ? 'superseded' : 'open';
+  if (operation !== 'confirm' && constraint.status === transitionStatus && !constraint.approvalEvidence) {
+    return { status: 'no-op', changed: false, taskId: resolved.taskId, qcrId: null, requestId: null, operations: [], error: null };
+  }
+  if (operation !== 'confirm' && constraint.status !== 'confirmed') return failed('QUALIFICATION_CONFIRMATION_REQUIRED', `constraint '${request.constraintId}' is not confirmed`, resolved.taskId);
+  if (parsed.qualification.constraintDigest !== request.expectedDigest) return failed('QUALIFICATION_DIGEST_CONFLICT', 'constraint digest changed before human confirmation', resolved.taskId);
+  let metadata;
+  try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
+  catch (error) { return failed('METADATA_CAPTURE_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId); }
+  const qcrId = operation === 'confirm' ? nextQcrId(content) : null;
+  const requestId = operation === 'confirm' ? requestIdFor(resolved.taskId, request.constraintId, request.expectedDigest, request.rationale.trim(), metadata.timestamp) : null;
+  const confirmedConstraint = qcrId ? {
+    constraintId: constraint.constraintId, statement: constraint.statement, status: 'confirmed' as const,
+    authority: 'human-declared', source: constraint.source, evidence: constraint.evidence,
+    derivedFrom: constraint.derivedFrom, approvalEvidence: qcrId
+  } : null;
+  const confirmation = confirmedConstraint && qcrId && requestId ? {
+    qcrId, constraintId: request.constraintId, actor: 'human-declared' as const, entrypoint: 'task-qualification' as const,
+    requestId, approvedDigest: constraintDigest(confirmedConstraint), confirmedAt: metadata.timestamp, rationale: request.rationale.trim()
+  } : null;
+  const confirmations = confirmation ? [...existing.confirmations, confirmation] : existing.confirmations;
+  const activity = locateActivityLog(content);
+  if (!activity) return failed('QUALIFICATION_ACTIVITY_MISSING', 'task has no unique Activity Log section', resolved.taskId);
+  const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
+    {
+      kind: 'table-row', action: 'upsert', sectionAliases: ['约束', 'Constraints'], columns: ['constraint_id', 'statement', 'status', 'authority', 'source', 'evidence', 'derived_from', 'approval_evidence'], keyColumn: 'constraint_id', key: constraint.constraintId,
+      values: { statement: constraint.statement, status: operation === 'confirm' ? 'confirmed' : transitionStatus, authority: operation === 'confirm' ? 'human-declared' : constraint.authority, source: constraint.source, evidence: constraint.evidence, derived_from: constraint.derivedFrom.join(','), approval_evidence: qcrId ?? '' }
+    },
+    ...(operation === 'confirm' ? [{ kind: 'section' as const, aliases: CONFIRMATION_HEADINGS, heading: findSectionHeading(content, [...CONFIRMATION_HEADINGS]), body: renderConfirmations(confirmations) }] : []),
+    { kind: 'section', aliases: ['活动日志', 'Activity Log'], heading: activity.heading, body: appendActivityEntry(activity, { time: metadata.timestamp, step: 'Qualification Confirmation', agent: 'human', note: operation === 'confirm' ? `${request.constraintId} confirmed → ${qcrId}` : `${request.constraintId} ${operation}d` }) }
+  ];
+  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, qcrId, requestId, operations: result.operations, error: null };
+}
+
+export { applyQualificationConfirmation };
+export type { QualificationConfirmationRequest, QualificationConfirmationResult };

package/lib/task/qualification-intents.ts

@@ -0,0 +1,150 @@
+import fs from 'node:fs';
+
+import { CONSTRAINT_COLUMNS, CANDIDATE_COLUMNS, parseTaskQualification } from './qualification-audit.ts';
+import type { CandidateStatus, ConstraintStatus } from './qualification-audit.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import type { TaskOperationSummary, TaskWriteOptions } from './write.ts';
+
+type QualificationConstraintProposal = {
+  constraintId: string;
+  statement: string;
+  status: Exclude<ConstraintStatus, 'confirmed'>;
+  authority: string;
+  source: string;
+  evidence: string;
+  derivedFrom: readonly string[];
+  approvalEvidence: string;
+};
+type QualificationCandidateProposal = {
+  candidateId: string;
+  statement: string;
+  status: Extract<CandidateStatus, 'pending'>;
+  constraintIds: readonly string[];
+  impact: string;
+  evidence: string;
+};
+type QualificationProposalRequest = {
+  taskRef: string;
+  expectedTaskInputDigest: string;
+  constraints?: readonly QualificationConstraintProposal[];
+  candidates?: readonly QualificationCandidateProposal[];
+  dryRun?: boolean;
+};
+type QualificationProposalResult = {
+  status: 'planned' | 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  taskId: string | null;
+  operations: readonly TaskOperationSummary[];
+  error: { code: string; message: string } | null;
+};
+
+function failed(code: string, message: string, taskId: string | null = null): QualificationProposalResult {
+  return { status: 'failed', changed: false, taskId, operations: [], error: { code, message } };
+}
+
+function validSingleLine(value: unknown): value is string {
+  return typeof value === 'string' && Boolean(value.trim()) && !/[\r\n]/.test(value);
+}
+
+function assertProposalKeys(value: unknown, keys: readonly string[], label: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const record = value as Record<string, unknown>;
+  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: unknown): QualificationConstraintProposal {
+  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] as string)) throw new Error(`constraint proposal '${key}' must be a single-line string`);
+  }
+  if (!/^C-[1-9]\d*$/.test(row.constraintId as string)) throw new Error(`constraint proposal id '${row.constraintId as string}' is invalid`);
+  if (row.status === 'confirmed' || !['derived', 'assumption', 'open', 'conflicted', 'superseded'].includes(row.status as string)) throw new Error('proposal cannot write confirmed constraint status');
+  if ((row.approvalEvidence as string) !== '') 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 as string, statement: row.statement as string, status: row.status as Exclude<ConstraintStatus, 'confirmed'>,
+    authority: row.authority as string, source: row.source as string, evidence: row.evidence as string,
+    derivedFrom: [...row.derivedFrom as string[]], approvalEvidence: ''
+  };
+}
+
+function parseCandidateProposal(value: unknown): QualificationCandidateProposal {
+  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 as string)) throw new Error(`candidate proposal id '${row.candidateId as string}' 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 as unknown as QualificationCandidateProposal;
+}
+
+function proposalValues(request: QualificationProposalRequest): { constraints: QualificationConstraintProposal[]; candidates: QualificationCandidateProposal[] } {
+  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: QualificationProposalRequest, options: TaskWriteOptions = {}): QualificationProposalResult {
+  if (!request || typeof request !== 'object' || !validSingleLine(request.taskRef)) return failed('QUALIFICATION_PROPOSAL_INVALID', 'taskRef is required');
+  let values: ReturnType<typeof proposalValues>;
+  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: string;
+  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: Parameters<typeof writeTask>[0]['mutations'][number][] = [];
+  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 };
+export type { QualificationCandidateProposal, QualificationConstraintProposal, QualificationProposalRequest, QualificationProposalResult };

package/lib/task/review-artifacts.ts

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { scanVisibleMarkdown } from './markdown.ts';
+
 type ReviewFindingCounts = {
   blocker: number;
   major: number;
@@ -51,23 +53,6 @@ function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function maxRound(entries: string[], stem: string): number {
-  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: string, round: number): string {
-  return round === 1 ? `${stem}.md` : `${stem}-r${round}.md`;
-}
-
 function normalizeVerdict(raw: unknown): ReviewVerdict | '' {
   const value = String(raw).trim().toLowerCase();
   if (value === '通过' || value === 'approved') return 'Approved';
@@ -77,29 +62,21 @@ function normalizeVerdict(raw: unknown): ReviewVerdict | '' {
 }
 
 function extractSection(content: string, names: string[]): string {
-  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) 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 scanned = scanVisibleMarkdown(content);
+  const heading = scanned.headings.find((item) => item.level === 2 && nameSet.has(item.text));
+  if (!heading) return '';
+  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: string): { start: number; end: number } | null {
-  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(
@@ -107,14 +84,19 @@ function uniqueLine(
   bounds: { start: number; end: number },
   pattern: RegExp
 ): { value: string; start: number; end: number } | null {
-  const section = content.slice(bounds.start, bounds.end);
-  const matches = [...section.matchAll(pattern)];
+  const matches: Array<{ value: string; index: number; length: number }> = [];
+  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
   };
 }
 
@@ -261,12 +243,10 @@ function parseVerdict(reviewPath: string): PathVerdictResult {
 }
 
 export {
-  artifactName,
   equalCounts,
   escapeRegExp,
   extractSection,
   finalizeReviewSummaryContent,
-  maxRound,
   normalizeVerdict,
   parseReviewSummary,
   parseVerdict,

package/lib/task/review-command.ts

@@ -0,0 +1,23 @@
+import type { ReviewFinalizationRequest } from './review-finalization.ts';
+
+export function parseReviewCommand(args: readonly string[]): ReviewFinalizationRequest & {
+  overrideTicket?: string; overrideTarget?: string; overrideScope?: string;
+} {
+  if (!args[0] || args[1] !== 'finalize-summary') throw new Error('task ref and finalize-summary are required');
+  const values: Record<string, string | boolean> = {};
+  const flags = {
+    '--stage': 'stage', '--artifact': 'artifact', '--orchestrated': 'orchestrated', '--dry-run': 'dryRun',
+    '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
+  } as const;
+  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 as keyof typeof flags];
+    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 } as ReturnType<typeof parseReviewCommand>;
+}