@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/task/artifact-lifecycle.ts

@@ -1,30 +1,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { ARTIFACT_FAMILY_CATALOG, artifactName, parseArtifactName } from './artifact-name.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { ResolveTaskRefErrorCode, TaskWorkspaceState } from './resolve-ref.ts';
-import { locateActivityLog } from './activity-log.ts';
+import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.ts';
 import { parseVerdict } from './review-artifacts.ts';
 import { extractSection, findSectionHeading } from './sections.ts';
 import { receiptForOutput, sha256File } from './artifact-receipts.ts';
 import { isArtifactInvalidated, parseInvalidationDocument } from './invalidation.ts';
 import type { InvalidationDocument } from './invalidation.ts';
+import { validateQualificationAudit } from './qualification-audit.ts';
+import type { ArtifactFamily, ArtifactFamilySpec } from './artifact-name.ts';
 
-const artifactFamilyCatalog = [
-  { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
-  { family: 'review-analysis', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['需求分析审查', 'Analysis Review'] },
-  { family: 'plan', sectionAliases: ['设计', 'Design'], heading: '设计', labels: ['技术方案', 'Technical Plan'] },
-  { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
-  { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
-  { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
-  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
-  { family: 'validation-run', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['验证运行证据', 'Validation Run Evidence'] },
-  { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
-] as const;
+const artifactFamilyCatalog = ARTIFACT_FAMILY_CATALOG;
+const ARTIFACT_STEPS: Readonly<Record<string, string>> = {
+  analysis: 'Analyze Task', 'review-analysis': 'Review Analysis',
+  plan: 'Plan Task', 'review-plan': 'Review Plan',
+  code: 'Code Task', 'review-code': 'Review Code'
+};
+
+/** Init, repair and finalization share the same authoritative round identity. */
+export function hasOpenArtifactRound(content: string, family: string, round: number): boolean {
+  const activity = locateActivityLog(content);
+  const step = ARTIFACT_STEPS[family];
+  if (!activity || !step) return false;
+  const qualifier = family === 'code'
+    ? '(?:, (?:fix for review-code(?:-r(?:[2-9]|[1-9]\\d+))?\\.md|decision II-[1-9]\\d*))?'
+    : '';
+  const expected = new RegExp(`^${step} \\(Round ${round}${qualifier}\\)$`);
+  return startedBackedRows(pairEntries(activity.entries)).filter((row) => expected.test(row.step) && !row.done).length === 1;
+}
 
-type ArtifactFamily = (typeof artifactFamilyCatalog)[number]['family'];
-type ArtifactFamilySpec = (typeof artifactFamilyCatalog)[number];
 type ArtifactIdentity = {
   family: ArtifactFamily;
   round: number;
@@ -85,7 +93,6 @@ type ArtifactContextResult = Omit<ArtifactInventoryResult, 'status'> & {
 };
 type InspectOptions = { repoRoot?: string };
 
-const FAMILY_SET = new Set<string>(artifactFamilyCatalog.map((item) => item.family));
 const BLOCKING_DIAGNOSTICS = new Set<ArtifactDiagnosticCode>([
   'NONCANONICAL_NAME', 'ROUND_OUT_OF_RANGE', 'MISSING_BASE', 'ROUND_GAP',
   'DUPLICATE_LOGICAL_ROUND', 'NON_REGULAR_FILE', 'SYMBOLIC_LINK',
@@ -96,27 +103,6 @@ function familySpec(family: string): ArtifactFamilySpec | null {
   return artifactFamilyCatalog.find((item) => item.family === family) ?? null;
 }
 
-function artifactName(family: ArtifactFamily, round: number): string {
-  if (!FAMILY_SET.has(family)) throw new Error(`unknown artifact family '${family}'`);
-  if (!Number.isSafeInteger(round) || round < 1) throw new Error('artifact round must be a safe positive integer');
-  return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
-}
-
-function parseArtifactName(name: string): { family: ArtifactFamily; round: number; name: string } | null {
-  if (path.basename(name) !== name) return null;
-  const matches: Array<{ family: ArtifactFamily; round: number; name: string }> = [];
-  for (const spec of artifactFamilyCatalog) {
-    if (name === `${spec.family}.md`) matches.push({ family: spec.family, round: 1, name });
-    const match = new RegExp(`^${escapeRegExp(spec.family)}-r([1-9]\\d*)\\.md$`).exec(name);
-    if (!match) continue;
-    const round = Number(match[1]);
-    if (Number.isSafeInteger(round) && round >= 2 && String(round) === match[1]) {
-      matches.push({ family: spec.family, round, name });
-    }
-  }
-  return matches.length === 1 ? matches[0]! : null;
-}
-
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -340,6 +326,7 @@ const OPTIONAL_CONTEXT: Partial<Record<ArtifactFamily, { family: ArtifactFamily;
   'manual-validation': { family: 'review-code' },
   'validation-run': { family: 'review-code' }
 };
+const QUALIFICATION_RECOVERY_OPTIONAL_CONTEXT_CONSUMERS = new Set<ArtifactFamily>(['analysis', 'plan']);
 
 function resolveArtifactContext(taskRef: string, family: string, options: InspectOptions = {}): ArtifactContextResult {
   const inventory = inspectTaskArtifacts(taskRef, family, options);
@@ -354,6 +341,8 @@ function resolveArtifactContext(taskRef: string, family: string, options: Inspec
     if (input.status === 'failed' || !input.latest) {
       return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_INPUT_MISSING', message: `latest ${required} artifact is required` } };
     }
+    const qualificationError = qualificationErrorForArtifact(input.latest);
+    if (qualificationError) return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: qualificationError } };
     inputs.push(input.latest);
   }
   const optional = OPTIONAL_CONTEXT[inventory.family as ArtifactFamily];
@@ -363,12 +352,27 @@ function resolveArtifactContext(taskRef: string, family: string, options: Inspec
       if (optional.requireReference && !context.reviewedInput) {
         return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: `${context.latest.name} has no valid reviewed input` } };
       }
+      const qualificationError = qualificationErrorForArtifact(context.latest);
+      if (qualificationError && !QUALIFICATION_RECOVERY_OPTIONAL_CONTEXT_CONSUMERS.has(inventory.family as ArtifactFamily)) {
+        return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: qualificationError } };
+      }
       inputs.push(context.latest);
     }
   }
   return { ...inventory, inputs, codeMode: null };
 }
 
+function qualificationErrorForArtifact(artifact: ArtifactIdentity): string | null {
+  try {
+    const taskContent = fs.readFileSync(path.join(path.dirname(artifact.path), 'task.md'), 'utf8');
+    const artifactContent = fs.readFileSync(artifact.path, 'utf8');
+    const result = validateQualificationAudit(taskContent, artifactContent);
+    return result.ok ? null : `${result.code}: ${result.message}`;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 function resolveCodeContext(inventory: ArtifactInventoryResult, options: InspectOptions): ArtifactContextResult {
   const taskRef = inventory.requestRef;
   const plan = inspectTaskArtifacts(taskRef, 'plan', options);
@@ -379,6 +383,16 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
   const codeMax = latestCode?.round ?? 0;
   const reviewMax = reviewCode.latest?.round ?? 0;
   const inputs = [plan.latest];
+  const planQualificationError = qualificationErrorForArtifact(plan.latest);
+  if (planQualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', planQualificationError);
+  if (latestCode) {
+    const qualificationError = qualificationErrorForArtifact(latestCode);
+    if (qualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', qualificationError, latestCode.name);
+  }
+  if (reviewCode.latest) {
+    const qualificationError = qualificationErrorForArtifact(reviewCode.latest);
+    if (qualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', qualificationError, reviewCode.latest.name);
+  }
   if (!latestCode) {
     if (!reviewPlan.latest || reviewPlan.reviewedInput?.name !== plan.latest.name) {
       return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `latest plan '${plan.latest.name}' requires a matching approved review-plan`);
@@ -398,6 +412,10 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
   if (reviewPlan.latest && !reviewPlan.reviewedInput) {
     return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `${reviewPlan.latest.name} has no valid reviewed input`, reviewPlan.latest.name);
   }
+  if (reviewPlan.latest) {
+    const qualificationError = qualificationErrorForArtifact(reviewPlan.latest);
+    if (qualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', qualificationError, reviewPlan.latest.name);
+  }
   if (reviewPlan.latest && reviewPlan.reviewedInput?.name === plan.latest.name) {
     const verdict = parseVerdict(reviewPlan.latest.path);
     if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_VERDICT_INVALID', `${verdict.code}: ${verdict.message}`, reviewPlan.latest.name);
@@ -409,8 +427,8 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
         `Latest ${reviewPlan.latest.name} approves plan content not captured by the latest code input receipt. Entering replan-driven init.`);
     }
   }
-  if (reviewMax < codeMax) {
-    const expected = artifactName('review-code', codeMax);
+  if (!reviewCode.latest || reviewCode.reviewedInput?.name !== latestCode.name) {
+    const expected = reviewCode.next?.name ?? artifactName('review-code', reviewMax + 1);
     return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `${expected} is required before another code round`, expected);
   }
   const review = reviewCode.latest;
@@ -496,6 +514,15 @@ function validateCompletedArtifact(taskDir: string, family: ArtifactFamily, name
   return artifact ? { ok: true, artifact } : { ok: false, error: { code: 'ARTIFACT_NOT_FOUND', message: `artifact '${name}' is not in inventory` } };
 }
 
+/** A candidate may replace its current slot or fill the next slot, never skip rounds. */
+export function validateArtifactPublication(taskDir: string, family: ArtifactFamily, name: string): ArtifactError | null {
+  const inventory = inspectArtifactDirectory(taskDir, family);
+  const error = assertWritableInventory(inventory);
+  if (error) return error;
+  if (inventory.next?.name === name || inventory.artifacts.some((artifact) => artifact.name === name)) return null;
+  return { code: 'ARTIFACT_IDENTITY_INVALID', message: `artifact '${name}' is not a current or next ${family} slot` };
+}
+
 function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity): {
   aliases: readonly string[];
   heading: string;
@@ -528,7 +555,7 @@ function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity):
 }
 
 export {
-  artifactFamilyCatalog, artifactName, parseArtifactName, familySpec,
+  artifactFamilyCatalog, familySpec,
   inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext,
   parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName,
   assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection

package/lib/task/artifact-name.ts

@@ -0,0 +1,55 @@
+type ArtifactFamily =
+  | 'analysis'
+  | 'review-analysis'
+  | 'plan'
+  | 'review-plan'
+  | 'code'
+  | 'review-code'
+  | 'manual-validation'
+  | 'validation-run'
+  | 'pr-review';
+
+type ArtifactFamilySpec = Readonly<{
+  family: ArtifactFamily;
+  sectionAliases: readonly [string, string];
+  heading: string;
+  labels: readonly [string, string];
+}>;
+
+const ARTIFACT_FAMILY_CATALOG = [
+  { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
+  { family: 'review-analysis', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['需求分析审查', 'Analysis Review'] },
+  { family: 'plan', sectionAliases: ['设计', 'Design'], heading: '设计', labels: ['技术方案', 'Technical Plan'] },
+  { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
+  { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
+  { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
+  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+  { family: 'validation-run', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['验证运行证据', 'Validation Run Evidence'] },
+  { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
+] as const satisfies readonly ArtifactFamilySpec[];
+
+const FAMILIES = new Set<string>(ARTIFACT_FAMILY_CATALOG.map(({ family }) => family));
+
+export function artifactName(family: ArtifactFamily, round: number): string {
+  if (!FAMILIES.has(family)) throw new Error(`unknown artifact family '${family}'`);
+  if (!Number.isSafeInteger(round) || round < 1) throw new Error('artifact round must be a safe positive integer');
+  return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
+}
+
+export function parseArtifactName(name: string): { family: ArtifactFamily; round: number; name: string } | null {
+  const match = /^(.+?)(?:-r([1-9]\d*))?\.md$/.exec(name);
+  if (!match || match[0] !== name || !FAMILIES.has(match[1]!)) return null;
+  const round = match[2] ? Number(match[2]) : 1;
+  if (!Number.isSafeInteger(round) || (match[2] && round < 2)) return null;
+  return { family: match[1] as ArtifactFamily, round, name };
+}
+
+export function maxArtifactRound(names: readonly string[], family: string): number {
+  return names.reduce((max, name) => {
+    const identity = parseArtifactName(name);
+    return identity?.family === family ? Math.max(max, identity.round) : max;
+  }, 0);
+}
+
+export { ARTIFACT_FAMILY_CATALOG };
+export type { ArtifactFamily, ArtifactFamilySpec };