@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/task/review-finalization.ts

@@ -2,8 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
-import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
-import { parseArtifactName, validateCompletedArtifact } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
+import { validateCompletedArtifact, hasOpenArtifactRound, validateArtifactPublication } from './artifact-lifecycle.ts';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
 import type { LedgerStageStatus, ReviewStage } from './ledger.ts';
 import { finalizeReviewSummaryContent } from './review-artifacts.ts';
@@ -14,6 +14,11 @@ import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-
 import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
 import { allowsManualOverride } from './guard-override.ts';
 import type { ManualOverrideCapability } from './guard-override.ts';
+import { getArtifactSchema } from './artifact-schema.ts';
+import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
+import { readArtifactRepairIntent, writeArtifactRepairIntent } from './artifact-repair-intent.ts';
+import type { ArtifactRepairOperation } from './artifact-operations.ts';
+import type { ArtifactRepairIntent } from './artifact-repair-intent.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -26,6 +31,7 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_SUMMARY_NOT_FOUND'
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH'
+  | 'REVIEW_ARTIFACT_STRUCTURE_INVALID'
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
@@ -48,6 +54,10 @@ type ReviewFinalizationResult = {
   stage: string;
   artifact: string;
   stageStatus: LedgerStageStatus | null;
+  artifactSha256: string | null;
+  semanticDigest: string | null;
+  repairable: boolean;
+  operation: ArtifactRepairOperation | null;
   operations: readonly {
     kind: 'artifact';
     artifact: string;
@@ -70,10 +80,10 @@ type ReviewFinalizationOptions = {
   lockAlreadyHeld?: boolean;
 };
 
-const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code'; action: string }> = {
-  analysis: { family: 'review-analysis', action: 'Review Analysis' },
-  plan: { family: 'review-plan', action: 'Review Plan' },
-  code: { family: 'review-code', action: 'Review Code' }
+const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code' }> = {
+  analysis: { family: 'review-analysis' },
+  plan: { family: 'review-plan' },
+  code: { family: 'review-code' }
 };
 const DEFAULT_FILE_SYSTEM: ReviewFileSystem = {
   readFileSync: (file) => fs.readFileSync(file, 'utf8'),
@@ -88,7 +98,8 @@ function failed(
   code: ReviewFinalizationErrorCode,
   message: string,
   taskId: string | null = null,
-  stageStatus: LedgerStageStatus | null = null
+  stageStatus: LedgerStageStatus | null = null,
+  extra: Partial<ReviewFinalizationResult> = {}
 ): ReviewFinalizationResult {
   return {
     status: 'failed',
@@ -99,20 +110,16 @@ function failed(
     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: string, action: string, round: number): boolean {
-  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: ReviewFileSystem, tempPath: string): void {
   try {
     fileSystem.unlinkSync(tempPath);
@@ -121,174 +128,167 @@ function cleanupTemp(fileSystem: ReviewFileSystem, tempPath: string): void {
   }
 }
 
-function finalizeReviewSummaryUnlocked(
+type ReviewSummaryCandidatePreparation = Readonly<{
+  result: ReviewFinalizationResult;
+  content: string;
+  provenance?: Parameters<typeof writeArtifactRepairIntent>[1];
+  expectedIntent?: ArtifactRepairIntent | null;
+}>;
+
+/** Prepare domain validation, summary bytes and provenance before any publication. */
+function prepareReviewSummaryCandidate(
   request: ReviewFinalizationRequest,
+  artifactContent: string,
   options: ReviewFinalizationOptions = {}
-): ReviewFinalizationResult {
+): ReviewSummaryCandidatePreparation {
+  let taskId: string | null = null;
+  let stageStatus: LedgerStageStatus | null = null;
+  const reject = (code: ReviewFinalizationErrorCode, message: string, extra: Partial<ReviewFinalizationResult> = {}): ReviewSummaryCandidatePreparation => ({
+    result: failed(request, code, message, taskId, stageStatus, extra), content: artifactContent
+  });
   const stage = request.stage as ReviewStage;
   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');
-  }
+  if (!spec) 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 });
-  if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
+  taskId = resolved.taskId ?? null;
+  if (!resolved.ok) 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);
+    return reject('TASK_STATE_MISMATCH', `task ${taskId} is ${resolved.state}, expected active`);
   }
-  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
-    );
+  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: string;
+  try { taskContent = (options.fileSystem?.readFileSync ?? DEFAULT_FILE_SYSTEM.readFileSync)(resolved.taskMdPath); }
+  catch (error) { return reject('REVIEW_ARTIFACT_NOT_REGULAR', String(error)); }
+  const artifactSha256 = sha256Content(artifactContent);
+  const semanticDigest = canonicalSemanticDigest(artifactContent);
+  const digests = { artifactSha256, semanticDigest };
+  let repairIntent;
+  try { repairIntent = readArtifactRepairIntent(resolved.repoRoot, taskId!, spec.family, request.artifact); }
+  catch (error) { 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 as const, taskId: taskId!, family: spec.family, artifact: request.artifact,
+        state: 'awaiting-repair' as const, 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 } : {})
+    };
   }
-  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);
+  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);
   }
-
-  const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
-  let taskContent: string;
-  let artifactContent: string;
-  try {
-    taskContent = fileSystem.readFileSync(resolved.taskMdPath);
-    artifactContent = fileSystem.readFileSync(validated.artifact.path);
-  } catch (error) {
-    return failed(request, 'REVIEW_ARTIFACT_NOT_REGULAR', String(error), resolved.taskId);
+  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);
+    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 reject('REVIEW_LEDGER_INVALID', String(error)); }
+  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' as const, ...finalDigests },
+      expectedIntent: repairIntent
+    } : {})
+  };
+}
+
+function commitReviewSummaryProvenance(
+  prepared: ReviewSummaryCandidatePreparation,
+  repoRoot: string
+): ReviewFinalizationResult {
+  try {
+    if (prepared.provenance) {
+      writeArtifactRepairIntent(repoRoot, prepared.provenance, { expected: prepared.expectedIntent ?? null });
     }
-    rows = ledger.rows;
+    return prepared.result;
   } catch (error) {
-    return failed(request, 'REVIEW_LEDGER_INVALID', String(error), resolved.taskId);
-  }
-  const ledgerError = validateLedgerRows(rows);
-  if (ledgerError) {
-    return failed(
-      request,
-      'REVIEW_LEDGER_INVALID',
-      `${ledgerError.code}: ${ledgerError.message}`,
-      resolved.taskId
-    );
-  }
-  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
-    );
-  }
-  const transformed = finalizeReviewSummaryContent(
-    artifactContent,
-    stageStatus.unresolvedFindingCounts
-  );
-  if (!transformed.ok) {
-    return failed(request, transformed.code, transformed.message, resolved.taskId, stageStatus);
-  }
-  if (!transformed.changed) {
-    return {
-      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
-      status: 'no-op',
-      error: null
-    };
-  }
-  const operations = [{ kind: 'artifact' as const, artifact: request.artifact, operation: 'update' as const }];
-  if (request.dryRun) {
-    return {
-      ...failed(request, 'REVIEW_ARTIFACT_CONFLICT', '', resolved.taskId, stageStatus),
-      status: 'planned',
-      changed: true,
-      operations,
-      error: null
-    };
+    return { ...prepared.result, status: 'failed', error: {
+      code: 'REVIEW_PROVENANCE_INVALID', message: `cannot record review provenance: ${String(error)}`
+    } };
   }
+}
 
-  const tempPath = path.join(
-    resolved.taskDir,
-    `.${request.artifact}.tmp-${process.pid}-${(options.randomSuffix ?? randomUUID)()}`
-  );
-  let mode: number;
+function finalizeReviewSummaryUnlocked(
+  request: ReviewFinalizationRequest,
+  options: ReviewFinalizationOptions = {}
+): ReviewFinalizationResult {
+  const spec = STAGES[request.stage as ReviewStage];
+  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);
+  }
+  const fileSystem = { ...DEFAULT_FILE_SYSTEM, ...options.fileSystem };
+  let content: string;
+  try { content = fileSystem.readFileSync(validated.artifact.path); }
+  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)()}`);
   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(
@@ -316,11 +316,12 @@ function finalizeReviewSummary(
   }
 }
 
-export { finalizeReviewSummary };
+export { finalizeReviewSummary, prepareReviewSummaryCandidate, commitReviewSummaryProvenance };
 export type {
   ReviewFinalizationError,
   ReviewFinalizationErrorCode,
   ReviewFinalizationOptions,
   ReviewFinalizationRequest,
-  ReviewFinalizationResult
+  ReviewFinalizationResult,
+  ReviewSummaryCandidatePreparation
 };

package/lib/task/review-fingerprint.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { artifactName, maxRound } from "./review-artifacts.ts";
+import { artifactName, maxArtifactRound } from "./artifact-name.ts";
 import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from "./invalidation.ts";
 
 type ReviewedGitTree = string & { readonly __reviewedGitTree: unique symbol };
@@ -45,7 +45,7 @@ export function resolvePostReviewGlobs(
 
 export function findAuthoritativeReviewCodeArtifact(taskDir: string) {
   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 };
   }

package/lib/task/sections.ts

@@ -1,4 +1,5 @@
 import type { FrontmatterScalar } from './frontmatter.ts';
+import { scanVisibleMarkdown } from './markdown.ts';
 
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -93,12 +94,14 @@ function parseTable(
     throw new DocumentMutationError('TASK_DOCUMENT_INVALID', 'table section is ambiguous');
   }
   const section = sections[0]!;
+  const visibleStarts = new Set(scanVisibleMarkdown(content).lines.map((line) => line.start));
   const sectionLines = linesOf(content).filter(
     (line) => line.start >= section.bodyStart && line.start < section.end
   );
   const firstContent = sectionLines.findIndex((line) => line.text.trim() !== '');
   const tables: number[] = [];
   for (let index = 0; index + 1 < sectionLines.length; index += 1) {
+    if (!visibleStarts.has(sectionLines[index]!.start) || !visibleStarts.has(sectionLines[index + 1]!.start)) continue;
     const header = splitTableCells(sectionLines[index]!.text);
     const separator = splitTableCells(sectionLines[index + 1]!.text);
     if (!header || !separator || header.cells.length !== input.columns.length) continue;
@@ -173,22 +176,24 @@ function documentEol(content: string): '\n' | '\r\n' {
 
 function matchingSections(content: string, aliases: readonly string[]) {
   const allowed = new Set(aliases);
-  return linesOf(content)
-    .map((line, index, lines) => {
-      const match = /^##\s+(.+?)\s*$/.exec(line.text);
-      if (!match?.[1] || !allowed.has(match[1])) return null;
-      let end = content.length;
-      for (let i = index + 1; i < lines.length; i += 1) {
-        if (/^##\s+/.test(lines[i]!.text)) {
-          end = lines[i]!.start;
-          break;
-        }
-      }
-      return { heading: match[1], line, bodyStart: line.end, end };
+  const lines = new Map(linesOf(content).map((line) => [line.start, line]));
+  const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2 || heading.level === 3);
+  return headings
+    .map((heading, index) => {
+      if (!allowed.has(heading.text)) return null;
+      const next = headings.slice(index + 1).find((candidate) => candidate.level <= heading.level);
+      const line = lines.get(heading.start)!;
+      return { heading: heading.text, level: heading.level, line, bodyStart: line.end, end: next?.start ?? content.length };
     })
     .filter((match): match is NonNullable<typeof match> => match !== null);
 }
 
+// Select the first visible section at the requested level, in document order.
+function findSectionRange(content: string, aliases: readonly string[], level: 2 | 3 = 2) {
+  const section = matchingSections(content, aliases).find((candidate) => candidate.level === level);
+  return section ? { start: section.line.start, bodyStart: section.bodyStart, end: section.end, heading: section.heading } : null;
+}
+
 function validateAliases(aliases: readonly string[], name: string): void {
   if (!Array.isArray(aliases) || aliases.length === 0 || aliases.some((alias) => !alias || /[\r\n]/.test(alias))) {
     throw new DocumentMutationError('MUTATION_INVALID', `${name} must contain headings`);
@@ -349,11 +354,13 @@ function mutateTableRow(content: string, mutation: TableRowMutation): TableMutat
     );
   }
   const section = sections[0]!;
+  const visibleStarts = new Set(scanVisibleMarkdown(content).lines.map((line) => line.start));
   const sectionLines = linesOf(content).filter(
     (line) => line.start >= section.bodyStart && line.start < section.end
   );
   const tables: { headerIndex: number; cells: string[] }[] = [];
   for (let i = 0; i + 1 < sectionLines.length; i += 1) {
+    if (!visibleStarts.has(sectionLines[i]!.start) || !visibleStarts.has(sectionLines[i + 1]!.start)) continue;
     const header = splitTableCells(sectionLines[i]!.text);
     const separator = splitTableCells(sectionLines[i + 1]!.text);
     if (!header || !separator || header.cells.length !== mutation.columns.length) continue;
@@ -475,24 +482,11 @@ function mutateTableRow(content: string, mutation: TableRowMutation): TableMutat
  * lines are trimmed. Returns '' when no alias heading is present.
  */
 function extractSection(content: string, aliases: string[]): string {
-  const lines = content.split('\n');
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i]!.trim();
-    if (aliases.some((alias) => new RegExp(`^##\\s+${escapeRegExp(alias)}\\s*$`).test(line))) {
-      start = i + 1;
-      break;
-    }
-  }
-  if (start === -1) return '';
-  let end = lines.length;
-  for (let i = start; i < lines.length; i += 1) {
-    if (/^##\s+/.test(lines[i]!)) {
-      end = i;
-      break;
-    }
-  }
-  return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+  const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2);
+  const index = headings.findIndex((heading) => aliases.includes(heading.text));
+  if (index === -1) return '';
+  return content.slice(headings[index]!.end + 1, headings[index + 1]?.start ?? content.length)
+    .replace(/^(?:\r?\n)+|(?:\r?\n)+$/g, '');
 }
 
 /**
@@ -501,10 +495,8 @@ function extractSection(content: string, aliases: string[]): string {
  * alias when none is present.
  */
 function findSectionHeading(content: string, aliases: string[]): string {
-  for (const alias of aliases) {
-    if (new RegExp(`^##\\s+${escapeRegExp(alias)}\\s*$`, 'm').test(content)) return alias;
-  }
-  return aliases[0]!;
+  const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2);
+  return aliases.find((alias) => headings.some((heading) => heading.text === alias)) ?? aliases[0]!;
 }
 
 /**
@@ -516,27 +508,16 @@ function findSectionHeading(content: string, aliases: string[]): string {
  * and trailing blank lines are trimmed. Returns '' when no match is present.
  */
 function extractSubSection(content: string, headingPrefix: string): string {
-  const lines = content.split('\n');
-  const headRe = new RegExp(`^###\\s+${escapeRegExp(headingPrefix)}(?![\\w-])`);
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    if (headRe.test(lines[i]!.trim())) {
-      start = i;
-      break;
-    }
-  }
-  if (start === -1) return '';
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i += 1) {
-    if (/^###?\s+/.test(lines[i]!)) {
-      end = i;
-      break;
-    }
-  }
-  return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+  const headings = scanVisibleMarkdown(content).headings.filter((heading) => heading.level === 2 || heading.level === 3);
+  const headRe = new RegExp(`^${escapeRegExp(headingPrefix)}(?![\\w-])`);
+  const index = headings.findIndex((heading) => heading.level === 3 && headRe.test(heading.text));
+  if (index === -1) return '';
+  return content.slice(headings[index]!.start, headings[index + 1]?.start ?? content.length)
+    .replace(/^(?:\r?\n)+|(?:\r?\n)+$/g, '');
 }
 
 export {
+  findSectionRange,
   extractSection,
   findSectionHeading,
   extractSubSection,

package/lib/task/verification-config.ts

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { getArtifactSchema } from './artifact-schema.ts';
+
 type VerificationConfig = {
   skill?: string;
   checks: Record<string, Record<string, unknown> | null>;
@@ -13,6 +15,16 @@ function loadVerificationConfig(repositoryRoot: string, skillName: string): Veri
   if (!parsed.checks || typeof parsed.checks !== 'object' || Array.isArray(parsed.checks)) {
     throw new Error(`config/verify.json has invalid checks for skill '${skillName}'`);
   }
+  const artifact = parsed.checks.artifact;
+  if (artifact && typeof artifact === 'object' && !Array.isArray(artifact)) {
+    const schema = artifact.schema;
+    if (schema !== undefined && (typeof schema !== 'string' || !getArtifactSchema(schema))) {
+      throw new Error(`config/verify.json has unknown artifact schema '${String(schema)}' for skill '${skillName}'`);
+    }
+    if (schema !== undefined && 'required_patterns' in artifact) {
+      throw new Error(`config/verify.json must not duplicate required_patterns for schema '${String(schema)}' in skill '${skillName}'`);
+    }
+  }
   return { ...(parsed.skill ? { skill: parsed.skill } : {}), checks: parsed.checks };
 }