@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/lib/task/events.ts

@@ -4,11 +4,16 @@ import { appendActivityEntry, locateActivityLog, pairEntries } from './activity-
 import {
   buildArtifactLinkSection,
   artifactName,
+  inspectArtifactDirectory,
+  parseReviewedInputReference,
+  parseCodePlanInputReference,
   parseArtifactName,
   resolveArtifactContext,
   validateCompletedArtifact
 } from './artifact-lifecycle.ts';
 import type { ArtifactContextResult, ArtifactErrorCode, ArtifactFamily, ArtifactIdentity } from './artifact-lifecycle.ts';
+import { ArtifactReceiptError, sha256File, upsertArtifactReceipt } from './artifact-receipts.ts';
+import type { ArtifactReceipt } from './artifact-receipts.ts';
 import { parseTypedTaskFrontmatter } from './frontmatter.ts';
 import {
   consumeImplementationInput,
@@ -35,7 +40,8 @@ const eventCatalog = [
   'review-plan.started', 'review-plan.completed',
   'code.started', 'code.completed',
   'review-code.started', 'review-code.completed',
-  'manual-validation.started', 'manual-validation.completed'
+  'manual-validation.started', 'manual-validation.completed',
+  'validation-run.started', 'validation-run.completed'
 ] as const;
 type TaskEventName = (typeof eventCatalog)[number];
 type Verdict = 'approved' | 'changes-requested' | 'rejected';
@@ -83,7 +89,9 @@ const SCHEMAS: Record<TaskEventName, { required?: string[]; optional?: string[]
   'review-code.started': { optional: ['round'] },
   'review-code.completed': { required: ['artifact', 'verdict', 'blockers', 'major', 'minor', 'manualValidation'], optional: ['round', 'orchestrated'] },
   'manual-validation.started': { optional: ['round'] },
-  'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] }
+  'manual-validation.completed': { required: ['artifact', 'summaryResult'], optional: ['round'] },
+  'validation-run.started': { optional: ['round'] },
+  'validation-run.completed': { required: ['artifact'], optional: ['round'] }
 };
 
 function validateTaskEventRequest(request: TaskEventRequest): TaskEventError | null {
@@ -121,7 +129,8 @@ const FAMILY = {
   'review-plan': { artifact: 'review-plan', started: ['technical-design', 'technical-design-review'], completed: ['technical-design', 'technical-design-review'], target: 'technical-design-review', label: 'Review Plan' },
   code: { artifact: 'code', started: ['technical-design-review', 'code-review'], completed: ['technical-design-review', 'code-review'], target: 'code', label: 'Code Task' },
   'review-code': { artifact: 'review-code', started: ['code', 'code-review', 'commit'], completed: ['code', 'code-review', 'commit'], target: 'code-review', label: 'Review Code' },
-  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' }
+  'manual-validation': { artifact: 'manual-validation', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Complete Manual Validation' },
+  'validation-run': { artifact: 'validation-run', started: ['code-review', 'commit'], completed: ['code-review', 'commit'], target: null, label: 'Run Manual Validation' }
 } as const;
 type EventFamily = keyof typeof FAMILY;
 
@@ -217,6 +226,7 @@ function identity(request: TaskEventRequest) {
   else if (family === 'plan') note = `Plan completed, awaiting human review → ${request.artifact}`;
   else if (family === 'code' && request.fixFor) note = `Fixed ${request.blockers} blockers, ${request.major} major, ${request.minor} minor issues${request.manualValidation ? `, skipped ${request.manualValidation} manual-validation` : ''} → ${request.artifact}`;
   else if (family === 'code') note = `Code implemented, ${request.filesModified} files modified, ${request.testsPassed} tests passed → ${request.artifact}`;
+  else if (family === 'validation-run') note = `Validation evidence recorded → ${request.artifact}`;
   else {
     const verdict = request.verdict === 'approved' ? 'Approved' : request.verdict === 'changes-requested' ? 'Changes Requested' : 'Rejected';
     note = `Verdict: ${verdict}, blockers: ${request.blockers}, major: ${request.major}, minor: ${request.minor}, Manual-validation: ${request.manualValidation} → ${request.artifact}`;
@@ -268,6 +278,80 @@ function openStartedIdentity(rows: ReturnType<typeof pairEntries>, family: Event
   return matches.length === 1 ? matches[0] : matches.length > 1 ? { conflict: true as const } : null;
 }
 
+function reviewInputFamily(family: EventFamily): ArtifactFamily {
+  return family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
+}
+
+function buildCompletionReceipt(
+  taskDir: string,
+  family: EventFamily,
+  artifact: ArtifactIdentity,
+  completedAt: string,
+  frontmatter: Record<string, unknown>
+): { ok: true; receipt: ArtifactReceipt } | { ok: false; message: string } | null {
+  if (family === 'code') {
+    let content: string;
+    try { content = fs.readFileSync(artifact.path, 'utf8'); }
+    catch (error) { return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` }; }
+    const input = parseCodePlanInputReference(content);
+    if (!input) return { ok: false, message: `${artifact.name} does not reference a canonical plan artifact` };
+    const startedInput = typeof frontmatter.code_input_artifact === 'string' ? frontmatter.code_input_artifact : '';
+    const startedSha256 = typeof frontmatter.code_input_sha256 === 'string' ? frontmatter.code_input_sha256 : '';
+    if (!startedInput || !startedSha256) return { ok: false, message: 'code.started plan input context is missing' };
+    if (input.name !== startedInput) return { ok: false, message: `${artifact.name} plan input '${input.name}' does not match code.started input '${startedInput}'` };
+    const plan = inspectArtifactDirectory(taskDir, 'plan');
+    if (plan.status !== 'ready' || !plan.latest || plan.latest.name !== input.name) {
+      return { ok: false, message: `code input '${input.name}' is not the latest plan artifact` };
+    }
+    try {
+      const inputSha256 = sha256File(plan.latest.path);
+      if (inputSha256 !== startedSha256) return { ok: false, message: `code input ${input.name} changed after code.started` };
+      return {
+        ok: true,
+        receipt: {
+          event: 'code.completed', output: artifact.name, input: input.name,
+          inputSha256, completedAt
+        }
+      };
+    } catch (error) {
+      return { ok: false, message: `cannot hash code input plan: ${error instanceof Error ? error.message : String(error)}` };
+    }
+  }
+  if (!family.startsWith('review-')) return null;
+  const expectedFamily = reviewInputFamily(family);
+  let content: string;
+  try { content = fs.readFileSync(artifact.path, 'utf8'); }
+  catch (error) { return { ok: false, message: `cannot read ${artifact.name}: ${String(error)}` }; }
+  const input = parseReviewedInputReference(content, expectedFamily);
+  if (!input) return { ok: false, message: `${artifact.name} does not reference a canonical ${expectedFamily} artifact` };
+  const startedInput = typeof frontmatter.review_input_artifact === 'string' ? frontmatter.review_input_artifact : '';
+  const startedSha256 = typeof frontmatter.review_input_sha256 === 'string' ? frontmatter.review_input_sha256 : '';
+  if (!startedInput || !startedSha256) return { ok: false, message: 'review started input context is missing' };
+  if (input.name !== startedInput) return { ok: false, message: `${artifact.name} input '${input.name}' does not match review.started input '${startedInput}'` };
+  const current = inspectArtifactDirectory(taskDir, expectedFamily);
+  if (current.status !== 'ready' || !current.latest || current.latest.name !== input.name) {
+    return { ok: false, message: `review input '${input.name}' is not the latest ${expectedFamily} artifact` };
+  }
+  const event = family === 'review-analysis'
+    ? 'review-analysis.completed' as const
+    : family === 'review-plan' ? 'review-plan.completed' as const : 'review-code.completed' as const;
+  try {
+    const stat = fs.lstatSync(current.latest.path);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('review input is not a regular file');
+    const inputSha256 = sha256File(current.latest.path);
+    if (inputSha256 !== startedSha256) return { ok: false, message: `review input ${input.name} changed after review.started` };
+    return {
+      ok: true,
+      receipt: {
+        event, output: artifact.name, input: input.name,
+        inputSha256, completedAt
+      }
+    };
+  } catch (error) {
+    return { ok: false, message: `cannot hash review input ${input.name}: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}
+
 function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOptions = {}): TaskEventResult {
   const invalid = validateTaskEventRequest(request);
   if (invalid) return failed(request, invalid);
@@ -342,7 +426,7 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   );
   if (findingCountError) return failed(normalized, findingCountError, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
   let orchestrationCompletion: OrchestrationStageCompletion | null = null;
-  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation') {
+  if (eventIdentity.phase === 'completed' && eventIdentity.family !== 'manual-validation' && eventIdentity.family !== 'validation-run') {
     const orchestrationStage = eventIdentity.family === 'analyze' ? 'analysis' : eventIdentity.family;
     const execution = validateLifecycleExecution(normalized.taskRef, {
       mode: normalized.orchestrated ? 'orchestrated' : 'standalone',
@@ -366,18 +450,60 @@ function applyTaskEventUnlocked(request: TaskEventRequest, options: TaskEventOpt
   let metadata;
   try { metadata = (options.metadataProvider ?? captureTaskWriteMetadata)(); }
   catch (error) { return failed(normalized, { code: 'METADATA_CAPTURE_FAILED', message: String(error) }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath }); }
+  let completionReceipt: ArtifactReceipt | null = null;
+  if (eventIdentity.phase === 'completed' && completedArtifact) {
+    const receipt = buildCompletionReceipt(resolved.taskDir, eventIdentity.family, completedArtifact, metadata.timestamp, frontmatter);
+    if (receipt && !receipt.ok) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: receipt.message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+    completionReceipt = receipt?.receipt ?? null;
+  }
   const step = eventIdentity.phase === 'started' || eventIdentity.target === null ? currentStep : eventIdentity.target;
   const logStep = eventIdentity.phase === 'started' ? `${eventIdentity.action} [started]` : eventIdentity.action;
   const body = appendActivityEntry(section, { time: metadata.timestamp, step: logStep, agent: normalized.agent, note: eventIdentity.note });
   const frontmatterSet: Record<string, string> = { current_step: step, assigned_to: normalized.agent };
+  let frontmatterRemove: string[] | undefined;
+  if (eventIdentity.phase === 'started' && eventIdentity.family === 'code') {
+    const planInput = artifactContext?.inputs.find((input) => input.family === 'plan');
+    if (!planInput) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: 'code.started plan input context is unavailable' }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    try {
+      frontmatterSet.code_input_artifact = planInput.name;
+      frontmatterSet.code_input_sha256 = sha256File(planInput.path);
+    } catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot hash code.started plan input: ${error instanceof Error ? error.message : String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+  } else if (eventIdentity.phase === 'completed' && eventIdentity.family === 'code') {
+    frontmatterRemove = ['code_input_artifact', 'code_input_sha256'];
+  } else if (eventIdentity.phase === 'started' && eventIdentity.family.startsWith('review-')) {
+    const expectedFamily = reviewInputFamily(eventIdentity.family);
+    const input = artifactContext?.inputs.find((candidate) => candidate.family === expectedFamily);
+    if (!input) return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `review.started ${expectedFamily} input context is unavailable` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    try {
+      frontmatterSet.review_input_artifact = input.name;
+      frontmatterSet.review_input_sha256 = sha256File(input.path);
+    } catch (error) {
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message: `cannot hash review.started input: ${error instanceof Error ? error.message : String(error)}` }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: step, action: eventIdentity.action, phase: eventIdentity.phase, artifactContext });
+    }
+  } else if (eventIdentity.phase === 'completed' && eventIdentity.family.startsWith('review-')) {
+    frontmatterRemove = ['review_input_artifact', 'review_input_sha256'];
+  }
   if (eventIdentity.phase === 'started' && normalized.implementationInput) frontmatterSet.last_reviewed_commit = '';
   const mutations: Parameters<typeof writeTask>[0]['mutations'][number][] = [
-    { kind: 'frontmatter', set: frontmatterSet }
+    { kind: 'frontmatter', set: frontmatterSet, remove: frontmatterRemove }
   ];
   if (completedArtifact) {
     const link = buildArtifactLinkSection(content, completedArtifact);
     mutations.push({ kind: 'section', aliases: link.aliases, heading: link.heading, body: link.body });
   }
+  if (completionReceipt) {
+    try {
+      const receiptSection = upsertArtifactReceipt(content, completionReceipt);
+      mutations.push({ kind: 'section', aliases: receiptSection.aliases, heading: receiptSection.heading, body: receiptSection.body });
+    } catch (error) {
+      const message = error instanceof ArtifactReceiptError ? error.message : String(error);
+      return failed(normalized, { code: 'EVENT_ARTIFACT_CONFLICT', message }, { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, fromStep: currentStep, toStep: currentStep, action: eventIdentity.action, phase: eventIdentity.phase });
+    }
+  }
   if (eventIdentity.phase === 'completed' && normalized.implementationInput) {
     let implementationRows;
     try {

package/lib/task/finalization-artifacts.ts

@@ -16,7 +16,8 @@ const COMPLETION_BACKFILL_FAMILIES = [
   'review-plan',
   'code',
   'review-code',
-  'manual-validation'
+  'manual-validation',
+  'validation-run'
 ] as const satisfies readonly ArtifactFamily[];
 
 type CompletionArtifactResult = {

package/lib/task/implementation-inputs.ts

@@ -131,13 +131,9 @@ function finalizeImplementationInput(
 }
 
 function selectPendingImplementationInput(
-  rows: readonly ImplementationInput[], reviewCompletedAt: string
+  rows: readonly ImplementationInput[]
 ): ImplementationInput | null {
-  const reviewEpoch = Date.parse(reviewCompletedAt.replace(' ', 'T'));
-  if (!Number.isFinite(reviewEpoch)) throw new Error('latest review completion time is invalid');
   const pending = rows.filter((row) => row.needsImplementation && row.status === 'pending');
-  const stale = pending.find((row) => Date.parse(row.decidedAt.replace(' ', 'T')) <= reviewEpoch);
-  if (stale) throw new Error(`implementation input ${stale.id} is not later than the latest approved review`);
   return [...pending].sort((left, right) => {
     const time = Date.parse(left.decidedAt.replace(' ', 'T')) - Date.parse(right.decidedAt.replace(' ', 'T'));
     return time || Number.parseInt(left.id.slice(3), 10) - Number.parseInt(right.id.slice(3), 10);

package/lib/task/index.ts

@@ -10,6 +10,7 @@ Commands:
   ls [--all | --blocked | --completed]   List tasks (default: active)
   show [--task <ref>]                    Print a task.md
   status [--task <ref>]                  Aggregated status view (metadata / artifacts / git / platform)
+  validate <ref> [options] -- <command>  Run host validation in snapshot or inplace scope
 
 Examples:
   ai task cat 11 analysis
@@ -29,6 +30,7 @@ Examples:
   ai task show 11
   ai task show TASK-20260612-162737
   ai task status 11
+  ai task validate 11 -- npm test
 
 Run 'ai task <command> --help' for details.`;
 
@@ -93,6 +95,12 @@ export async function runTask(args: string[]): Promise<void> {
       status(rest);
       break;
     }
+    case 'validate': {
+      const { validate } = await import('./commands/validate.ts');
+      const exitCode = await validate(rest);
+      if (exitCode !== 0) process.exitCode = exitCode;
+      break;
+    }
     default:
       process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
       process.stdout.write(`${USAGE}\n`);

package/lib/task/ledger.ts

@@ -61,7 +61,22 @@ function validateLedgerRows(rows: readonly LedgerRow[]): LedgerValidationError |
   for (const row of rows) {
     if (seen.has(row.id)) return { code: 'LEDGER_DUPLICATE_ID', message: `duplicate ledger id '${row.id}'` };
     seen.add(row.id);
-    if (/^PRC-[1-9]\d*$/.test(row.id)) continue;
+    if (/^PRC-[1-9]\d*$/.test(row.id)) {
+      if (
+        row.stage !== 'post-review-commit' ||
+        row.round !== '-' ||
+        row.severity !== '-' ||
+        row.status !== 'human-decided' ||
+        row.evidence === '' ||
+        /[\r\n]/.test(row.evidence)
+      ) {
+        return { code: 'LEDGER_DOCUMENT_INVALID', message: `post-review exemption row '${row.id}' is invalid` };
+      }
+      continue;
+    }
+    if (row.stage === 'post-review-commit') {
+      return { code: 'LEDGER_DOCUMENT_INVALID', message: `post-review exemption row '${row.id}' must use a PRC id` };
+    }
     if (!/^(AN|PL|CD|HD)-[1-9]\d*$/.test(row.id)) return { code: 'LEDGER_ID_INVALID', message: `ledger id '${row.id}' is invalid` };
     if (!['analysis', 'plan', 'code', 'post-review-commit'].includes(row.stage)) return { code: 'LEDGER_STAGE_INVALID', message: `ledger stage '${row.stage}' is invalid` };
     if (!FINDING_STATUSES.has(row.status)) return { code: 'LEDGER_STATUS_INVALID', message: `ledger status '${row.status}' is invalid` };