@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/task/artifact-repair-intent.ts

@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+import type { ArtifactSchemaFamily } from './artifact-schema.ts';
+
+export type ArtifactRepairPhase =
+  | 'orchestration.prepare'
+  | 'artifact.finalize-local'
+  | 'task-event.completed';
+export type ArtifactRepairState = 'awaiting-repair' | 'finalize-ready' | 'commit-started' | 'passed' | 'consumed';
+
+export type ArtifactRepairIntent = Readonly<{
+  version: 2;
+  taskId: string;
+  family: ArtifactSchemaFamily;
+  artifact: string;
+  state: ArtifactRepairState;
+  baselineSemanticDigest: string | null;
+  artifactSha256: string;
+  semanticDigest: string;
+  recoveryOperationId: string | null;
+  phase: ArtifactRepairPhase | null;
+  authorityDigest: string | null;
+  requestId: string;
+  createdAt: number;
+  updatedAt: number;
+}>;
+
+function intentRoot(repoRoot: string): string {
+  return path.join(repoRoot, '.agents', 'workspace', '.local-artifact-finalization-intents');
+}
+
+function intentPath(repoRoot: string, taskId: string, family: ArtifactSchemaFamily, artifact: string): string {
+  return path.join(intentRoot(repoRoot), `${taskId}-${family}-${artifact}.json`);
+}
+
+function validDigest(value: unknown): value is string {
+  return typeof value === 'string' && /^[a-f0-9]{64}$/u.test(value);
+}
+
+function validTaskId(value: unknown): value is string {
+  return typeof value === 'string' && /^TASK-\d{8}-\d{6}$/u.test(value);
+}
+
+function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+
+export function isArtifactRepairIntent(value: unknown): value is ArtifactRepairIntent {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const intent = value as Record<string, unknown>;
+  return exactKeys(intent, [
+    'artifact', 'artifactSha256', 'authorityDigest', 'baselineSemanticDigest', 'createdAt',
+    'family', 'phase', 'recoveryOperationId', 'requestId', 'semanticDigest', 'state',
+    'taskId', 'updatedAt', 'version'
+  ])
+    && intent.version === 2
+    && validTaskId(intent.taskId)
+    && typeof intent.family === 'string'
+    && ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'].includes(intent.family)
+    && typeof intent.artifact === 'string' && intent.artifact.length > 0
+    && ['awaiting-repair', 'finalize-ready', 'commit-started', 'passed', 'consumed'].includes(String(intent.state))
+    && (intent.baselineSemanticDigest === null || validDigest(intent.baselineSemanticDigest))
+    && validDigest(intent.artifactSha256)
+    && validDigest(intent.semanticDigest)
+    && (intent.recoveryOperationId === null || (typeof intent.recoveryOperationId === 'string' && /^[a-f0-9-]{16,64}$/u.test(intent.recoveryOperationId)))
+    && (intent.phase === null || ['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(String(intent.phase)))
+    && (intent.authorityDigest === null || validDigest(intent.authorityDigest))
+    && typeof intent.requestId === 'string' && intent.requestId.length > 0 && !/[\r\n]/u.test(intent.requestId)
+    && Number.isSafeInteger(intent.createdAt) && Number.isSafeInteger(intent.updatedAt)
+    && (intent.state === 'awaiting-repair' ? intent.baselineSemanticDigest === intent.semanticDigest : true);
+}
+
+function readArtifactRepairIntent(
+  repoRoot: string,
+  taskId: string,
+  family: ArtifactSchemaFamily,
+  artifact: string
+): ArtifactRepairIntent | null {
+  const target = intentPath(repoRoot, taskId, family, artifact);
+  if (!fs.existsSync(target)) return null;
+  let value: unknown;
+  try { value = JSON.parse(fs.readFileSync(target, 'utf8')) as unknown; }
+  catch (error) { throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`); }
+  if (!isArtifactRepairIntent(value) || value.taskId !== taskId || value.family !== family || value.artifact !== artifact) {
+    throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+  }
+  return value;
+}
+
+export function writeArtifactRepairIntent(
+  repoRoot: string,
+  value: ArtifactRepairIntent,
+  options: Readonly<{ expected?: ArtifactRepairIntent | null }> = {}
+): void {
+  if (!isArtifactRepairIntent(value)) throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+  const directory = intentRoot(repoRoot);
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const target = intentPath(repoRoot, value.taskId, value.family, value.artifact);
+  const lock = `${target}.lock`;
+  let descriptor: number;
+  try { descriptor = fs.openSync(lock, 'wx', 0o600); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: another provenance writer owns the intent');
+    }
+    throw error;
+  }
+  try {
+    const current = fs.existsSync(target)
+      ? readArtifactRepairIntent(repoRoot, value.taskId, value.family, value.artifact)
+      : null;
+    if (!isDeepStrictEqual(current, options.expected ?? null)) {
+      throw new Error('ARTIFACT_REPAIR_INTENT_CONFLICT: repair provenance changed during finalization');
+    }
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    try { fs.renameSync(temporary, target); }
+    catch (error) {
+      try { fs.unlinkSync(temporary); } catch { /* preserve primary error */ }
+      throw error;
+    }
+  } finally {
+    fs.closeSync(descriptor);
+    try { fs.unlinkSync(lock); } catch { /* preserve the primary result */ }
+  }
+}
+
+export function findArtifactRepairIntentsByOperation(
+  repoRoot: string,
+  operationId: string
+): readonly ArtifactRepairIntent[] {
+  if (!operationId || /[\r\n]/u.test(operationId)) {
+    throw new Error('ARTIFACT_REPAIR_OPERATION_INVALID: recovery operation id is invalid');
+  }
+  const directory = intentRoot(repoRoot);
+  if (!fs.existsSync(directory)) return Object.freeze([]);
+  return Object.freeze(fs.readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => {
+      const target = path.join(directory, name);
+      let value: unknown;
+      try { value = JSON.parse(fs.readFileSync(target, 'utf8')) as unknown; }
+      catch (error) { throw new Error(`ARTIFACT_REPAIR_INTENT_INVALID: ${String(error)}`); }
+      if (!isArtifactRepairIntent(value)) throw new Error('ARTIFACT_REPAIR_INTENT_INVALID: repair provenance schema is invalid');
+      return value;
+    })
+    .filter((value) => value.recoveryOperationId === operationId));
+}
+
+export { readArtifactRepairIntent };

package/lib/task/artifact-schema.ts

@@ -0,0 +1,163 @@
+import { parseArtifactName } from './artifact-name.ts';
+import type { ArtifactFamily } from './artifact-name.ts';
+
+type ArtifactSchemaFamily = Exclude<ArtifactFamily, 'manual-validation' | 'validation-run' | 'pr-review'>;
+type ArtifactLocale = 'zh-CN' | 'en';
+type ArtifactSection = Readonly<{
+  id: string;
+  order: number;
+  headings: Readonly<{ zh: string; en: string }>;
+  marker: string;
+}>;
+type ArtifactSchema = Readonly<{
+  family: ArtifactSchemaFamily;
+  title: Readonly<{ zh: string; en: string }>;
+  sections: readonly ArtifactSection[];
+  requiredPatterns: readonly string[];
+}>;
+type ArtifactSkeletonInput = Readonly<{
+  taskId: string;
+  family: ArtifactSchemaFamily;
+  artifact: string;
+  locale?: ArtifactLocale;
+}>;
+
+const LOCAL_SECTIONS = {
+  analysis: [
+    ['source', '需求来源', 'Requirements Source'],
+    ['understanding', '需求理解', 'Requirements Understanding'],
+    ['files', '相关文件', 'Related Files'],
+    ['impact', '影响评估', 'Impact Assessment'],
+    ['risks', '技术风险', 'Technical Risks'],
+    ['effort', '工作量和复杂度评估', 'Effort and Complexity Assessment'],
+    ['state-check', '状态核对', 'State Check']
+  ],
+  plan: [
+    ['understanding', '问题理解', 'Problem Understanding'],
+    ['constraints', '约束条件', 'Constraints'],
+    ['options', '方案对比', 'Options Comparison'],
+    ['approach', '技术方法', 'Technical Approach'],
+    ['steps', '实施步骤', 'Implementation Steps'],
+    ['files', '文件清单', 'File List'],
+    ['verification', '验证策略', 'Verification Strategy'],
+    ['state-check', '状态核对', 'State Check']
+  ],
+  code: [
+    ['input', '实现输入', 'Implementation Input'],
+    ['files', '变更文件', 'Changed Files'],
+    ['key-code', '关键代码说明', 'Key Code Notes'],
+    ['tests', '测试结果', 'Test Results'],
+    ['deviations', '与方案的差异', 'Differences from Plan'],
+    ['review-focus', '供审查关注的内容', 'Review Focus'],
+    ['state-check', '状态核对', 'State Check'],
+    ['evidence', '证据原文', 'Raw Evidence']
+  ],
+  'review-analysis': [
+    ['summary', '审查摘要', 'Review Summary'],
+    ['coverage', '检视覆盖声明', 'Inspection Coverage'],
+    ['specialized-coverage', '需求分析专项覆盖', 'Requirements Analysis Coverage'],
+    ['traceability', '追踪矩阵', 'Traceability Matrix'],
+    ['issues', '问题清单', 'Findings'],
+    ['non-blocking', '非阻塞建议', 'Non-blocking Suggestions'],
+    ['manual-validation', '人工校验项', 'Manual Validation Items'],
+    ['conclusion', '结论与建议', 'Conclusion and Recommendation'],
+    ['state-check', '状态核对', 'State Check'],
+    ['evidence', '证据原文', 'Raw Evidence'],
+    ['self-critique', '自我质疑', 'Self-critique'],
+    ['ledger-writeback', '审查分歧账本回写', 'Review Disagreement Ledger Write-back']
+  ],
+  'review-plan': [
+    ['summary', '审查摘要', 'Review Summary'],
+    ['coverage', '检视覆盖声明', 'Inspection Coverage'],
+    ['specialized-coverage', '技术方案架构覆盖', 'Technical Plan Architecture Coverage'],
+    ['traceability', '追踪矩阵', 'Traceability Matrix'],
+    ['issues', '问题清单', 'Findings'],
+    ['non-blocking', '非阻塞建议', 'Non-blocking Suggestions'],
+    ['manual-validation', '人工校验项', 'Manual Validation Items'],
+    ['conclusion', '结论与建议', 'Conclusion and Recommendation'],
+    ['state-check', '状态核对', 'State Check'],
+    ['evidence', '证据原文', 'Raw Evidence'],
+    ['self-critique', '自我质疑', 'Self-critique'],
+    ['ledger-writeback', '审查分歧账本回写', 'Review Disagreement Ledger Write-back']
+  ],
+  'review-code': [
+    ['summary', '审查摘要', 'Review Summary'],
+    ['coverage', '检视覆盖声明', 'Inspection Coverage'],
+    ['specialized-coverage', '代码实现专项覆盖', 'Code Implementation Coverage'],
+    ['traceability', '追踪矩阵', 'Traceability Matrix'],
+    ['issues', '问题清单', 'Findings'],
+    ['non-blocking', '非阻塞建议', 'Non-blocking Suggestions'],
+    ['manual-validation', '人工校验项', 'Manual Validation Items'],
+    ['conclusion', '结论与建议', 'Conclusion and Recommendation'],
+    ['state-check', '状态核对', 'State Check'],
+    ['evidence', '证据原文', 'Raw Evidence'],
+    ['self-critique', '自我质疑', 'Self-critique'],
+    ['ledger-writeback', '审查分歧账本回写', 'Review Disagreement Ledger Write-back']
+  ]
+} as const;
+
+function buildSections(family: ArtifactSchemaFamily): readonly ArtifactSection[] {
+  return LOCAL_SECTIONS[family].map(([id, zh, en], index) => ({
+    id,
+    order: index + 1,
+    headings: { zh, en },
+    marker: `artifact-section:${family}:${id}`
+  }));
+}
+
+const ARTIFACT_SCHEMAS: readonly ArtifactSchema[] = [
+  { family: 'analysis', title: { zh: '需求分析报告', en: 'Requirements Analysis' }, sections: buildSections('analysis'), requiredPatterns: ['^\\$ '] },
+  { family: 'review-analysis', title: { zh: '需求分析审查报告', en: 'Analysis Review Report' }, sections: buildSections('review-analysis'), requiredPatterns: ['^### (?:审查决定|Approval Decision)$', '^\\$ '] },
+  { family: 'plan', title: { zh: '技术方案', en: 'Technical Plan' }, sections: buildSections('plan'), requiredPatterns: ['^\\$ '] },
+  { family: 'review-plan', title: { zh: '技术方案审查报告', en: 'Plan Review Report' }, sections: buildSections('review-plan'), requiredPatterns: ['^### (?:审查决定|Approval Decision)$', '^\\$ '] },
+  { family: 'code', title: { zh: '实现报告', en: 'Implementation Report' }, sections: buildSections('code'), requiredPatterns: ['^\\$ '] },
+  { family: 'review-code', title: { zh: '代码审查报告', en: 'Code Review Report' }, sections: buildSections('review-code'), requiredPatterns: [
+    '^### (?:审查决定|Approval Decision)$',
+    '^\\$ ',
+    '^- \\*\\*(?:总体结论|Overall Verdict)\\*\\*[:：]\\s*(?:通过|需要修改|拒绝|Approved|Changes Requested|Rejected)\\s*$',
+    '^- \\*\\*(?:审查基线提交|Review Baseline Commit)\\*\\*[:：]\\s*\\S',
+    '^- \\*\\*(?:审查差异基线|Reviewed Diff Base)\\*\\*[:：]\\s*[0-9a-f]{40,64}\\s*$',
+    '^- \\*\\*(?:审查差异指纹|Reviewed Diff Fingerprint)\\*\\*[:：]\\s*sha256:[0-9a-f]{64}\\s*$',
+    '^- \\*\\*(?:审查快照树|Reviewed Snapshot Tree)\\*\\*[:：]\\s*[0-9a-f]{40,64}\\s*$'
+  ] }
+];
+
+function getArtifactSchema(family: string): ArtifactSchema | null {
+  return ARTIFACT_SCHEMAS.find((schema) => schema.family === family) ?? null;
+}
+
+function renderArtifactSkeleton(input: ArtifactSkeletonInput): string {
+  const schema = getArtifactSchema(input.family);
+  if (!schema) throw new Error(`unknown artifact schema family '${input.family}'`);
+  const locale = input.locale ?? 'zh-CN';
+  const identity = parseArtifactName(input.artifact);
+  if (identity?.family !== input.family) throw new Error(`invalid artifact identity '${input.artifact}' for '${input.family}'`);
+  const round = identity.round;
+  const title = schema.title[locale === 'en' ? 'en' : 'zh'];
+  const headings = locale === 'en' ? 'en' : 'zh';
+  const lines = [
+    `<!-- artifact-context:${input.taskId}:${input.family}:${round} -->`,
+    `# ${title}`,
+    ''
+  ];
+  for (const section of schema.sections) {
+    lines.push(`## ${section.headings[headings]}`);
+    lines.push(`<!-- ${section.marker} -->`);
+    lines.push('<!-- artifact-slot:empty -->');
+    lines.push('');
+  }
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export {
+  ARTIFACT_SCHEMAS,
+  getArtifactSchema,
+  renderArtifactSkeleton
+};
+export type {
+  ArtifactLocale,
+  ArtifactSchema,
+  ArtifactSchemaFamily,
+  ArtifactSection,
+  ArtifactSkeletonInput
+};

package/lib/task/capabilities.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { parseArtifactName } from './artifact-name.ts';
 import type { InvalidationDocument } from './invalidation.ts';
 import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from './invalidation.ts';
 import { receiptForOutput } from './artifact-receipts.ts';
@@ -11,6 +12,10 @@ import { parseReworkIntentDocument } from './rework-intent.ts';
 import type { ReworkIntent } from './rework-intent.ts';
 import { sha256File } from './artifact-receipts.ts';
 import { hasOpenLifecycleExecution } from './activity-log.ts';
+import { parseQualificationAudit, parseTaskQualification } from './qualification-audit.ts';
+import type { QualificationAudit, TaskQualification } from './qualification-audit.ts';
+
+const ARTIFACT_AUDIT_FAMILIES = new Set(['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code']);
 
 type LifecycleAction =
   | 'analysis' | 'review-analysis' | 'plan' | 'review-plan'
@@ -42,6 +47,8 @@ type LifecycleFacts = {
   unresolvedLedger: Record<'analysis' | 'plan' | 'code', number>;
   executionBusy: boolean;
   recommendedAction?: LifecycleAction | null;
+  qualificationStale?: boolean;
+  qualificationStaleArtifacts?: readonly string[];
 };
 type CapabilityResult = {
   allowed: boolean;
@@ -86,6 +93,9 @@ function canStart(action: LifecycleAction, facts: LifecycleFacts, trigger: Expli
   }
   if (facts.taskState !== 'active') return deny('TASK_NOT_ACTIVE', `state=${facts.taskState}`);
   if (invalidationBlocks(facts.invalidation)) return deny('INVALIDATION_INCOMPLETE');
+  if (facts.qualificationStale && facts.recommendedAction !== action) {
+    return deny('QUALIFICATION_STALE', ...(facts.qualificationStaleArtifacts ?? ['qualification audit is stale']));
+  }
   if (facts.executionBusy) return deny('EXECUTION_BUSY');
 
   const implicit = trigger.explicitRequest === false;
@@ -132,13 +142,9 @@ function canStart(action: LifecycleAction, facts: LifecycleFacts, trigger: Expli
   return deny('CAPABILITY_ACTION_UNKNOWN');
 }
 
-function artifactRound(name: string): number {
-  const match = /-r(\d+)\.md$/.exec(name);
-  return match ? Number(match[1]) : 1;
-}
-
 function latestArtifact(names: readonly string[]): string | null {
-  return [...names].sort((left, right) => artifactRound(right) - artifactRound(left) || left.localeCompare(right))[0] ?? null;
+  return names.map(parseArtifactName).filter((identity) => identity !== null)
+    .sort((left, right) => right.round - left.round || left.name.localeCompare(right.name))[0]?.name ?? null;
 }
 
 function reviewedInputName(content: string, expectedFamily: 'analysis' | 'plan' | 'code'): string | null {
@@ -154,8 +160,42 @@ function reviewMatchesLatest(facts: LifecycleFacts, source: 'analysis' | 'plan'
   return Boolean(latestSource && facts.reviewedInputs?.[review] === latestSource);
 }
 
+function qualificationCandidateSnapshotMatches(
+  audit: QualificationAudit,
+  qualification: TaskQualification
+): boolean {
+  const current = new Map(qualification.candidates.map((candidate) => [candidate.candidateId, candidate]));
+  return audit.candidateQualifications.length === current.size && audit.candidateQualifications.every((row) => {
+    const candidate = current.get(row.candidateId);
+    return Boolean(candidate && candidate.status === row.status && candidate.impact === row.impact
+      && candidate.evidence === row.evidence && candidate.constraintIds.join(',') === row.constraintIds.join(','));
+  });
+}
+
+const QUALIFICATION_RECOVERY_ORDER: ReadonlyArray<{ action: LifecycleAction; pattern: RegExp }> = [
+  { action: 'analysis', pattern: /^analysis(?:-r\d+)?\.md$/ },
+  { action: 'review-analysis', pattern: /^review-analysis(?:-r\d+)?\.md$/ },
+  { action: 'plan', pattern: /^plan(?:-r\d+)?\.md$/ },
+  { action: 'review-plan', pattern: /^review-plan(?:-r\d+)?\.md$/ },
+  { action: 'code', pattern: /^code(?:-r\d+)?\.md$/ },
+  { action: 'review-code', pattern: /^review-code(?:-r\d+)?\.md$/ }
+];
+
+function qualificationRecoveryAction(facts: LifecycleFacts): LifecycleAction | null {
+  const stale = facts.qualificationStaleArtifacts ?? [];
+  return QUALIFICATION_RECOVERY_ORDER.find(({ pattern }) => stale.some((name) => pattern.test(name)))?.action ?? null;
+}
+
 function recommendNext(facts: LifecycleFacts): LifecycleRecommendation {
   if (invalidationBlocks(facts.invalidation)) return { action: null, reasonCode: 'INVALIDATION_INCOMPLETE', evidence: ['reconcile task invalidation before routing'] };
+  if (facts.qualificationStale) {
+    const action = qualificationRecoveryAction(facts);
+    return {
+      action,
+      reasonCode: 'QUALIFICATION_RECOVERY_REQUIRED',
+      evidence: facts.qualificationStaleArtifacts ?? ['qualification audit is stale']
+    };
+  }
   const pendingIntent = (facts.reworkIntents ?? []).find((intent) => intent.status === 'pending');
   if (pendingIntent) return { action: pendingIntent.target, reasonCode: 'REWORK_INTENT_PENDING', evidence: [pendingIntent.intentId, pendingIntent.findingId] };
   if (!hasArtifact(facts, 'analysis')) return { action: 'analysis', reasonCode: 'ANALYSIS_ARTIFACT_MISSING', evidence: ['analysis artifact is absent'] };
@@ -199,17 +239,11 @@ function buildLifecycleFacts(taskDir: string, content: string, taskState = 'acti
       const stat = fs.lstatSync(path.join(taskDir, name));
       return stat.isFile() && !stat.isSymbolicLink();
     });
-    const artifactFamilies = {
-      analysis: /^analysis(?:-r\d+)?\.md$/,
-      'review-analysis': /^review-analysis(?:-r\d+)?\.md$/,
-      plan: /^plan(?:-r\d+)?\.md$/,
-      'review-plan': /^review-plan(?:-r\d+)?\.md$/,
-      code: /^code(?:-r\d+)?\.md$/,
-      'review-code': /^review-code(?:-r\d+)?\.md$/
-    } as const;
-    const familyFor = (name: string): keyof typeof artifactFamilies | null =>
-      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>)
-        .find((family) => artifactFamilies[family].test(name)) ?? null;
+    const artifactFamilies = ['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code'] as const;
+    const familyFor = (name: string) => {
+      const family = parseArtifactName(name)?.family;
+      return artifactFamilies.find((candidate) => candidate === family) ?? null;
+    };
     const activeFiles = files.filter((name) => {
       const family = familyFor(name);
       return !family || !isArtifactInvalidated(invalidation.document, family, name);
@@ -217,15 +251,37 @@ function buildLifecycleFacts(taskDir: string, content: string, taskState = 'acti
     const artifactHashes: Record<string, string> = {};
     for (const name of activeFiles) artifactHashes[name] = sha256File(path.join(taskDir, name));
     const artifacts: Partial<Record<LifecycleAction, readonly string[]>> = Object.fromEntries(
-      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>).map((family) => [
-        family, activeFiles.filter((name) => artifactFamilies[family].test(name))
+      artifactFamilies.map((family) => [
+        family, activeFiles.filter((name) => familyFor(name) === family)
       ])
     ) as Partial<Record<LifecycleAction, readonly string[]>>;
     const staleArtifacts: Partial<Record<LifecycleAction, readonly string[]>> = Object.fromEntries(
-      (Object.keys(artifactFamilies) as Array<keyof typeof artifactFamilies>).map((family) => [
-        family, files.filter((name) => artifactFamilies[family].test(name) && isArtifactInvalidated(invalidation.document, family, name))
+      artifactFamilies.map((family) => [
+        family, files.filter((name) => familyFor(name) === family && isArtifactInvalidated(invalidation.document, family, name))
       ])
     ) as Partial<Record<LifecycleAction, readonly string[]>>;
+    const qualification = parseTaskQualification(content);
+    if (!qualification.ok) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: qualification.message };
+    const qualificationStaleArtifacts: string[] = [];
+    if (qualification.qualification.present) {
+      const constraints = new Map(qualification.qualification.constraints.map((row) => [row.constraintId, row.digest]));
+      for (const family of artifactFamilies) {
+        if (!ARTIFACT_AUDIT_FAMILIES.has(family)) continue;
+        const name = latestArtifact(artifacts[family] ?? []);
+        if (!name) continue;
+        let auditContent: string;
+        try { auditContent = fs.readFileSync(path.join(taskDir, name), 'utf8'); }
+        catch { qualificationStaleArtifacts.push(name); continue; }
+        const audit = parseQualificationAudit(auditContent);
+        if (!audit.ok || !audit.audit.present || !audit.audit.snapshot) { qualificationStaleArtifacts.push(name); continue; }
+        const constraintsChanged = audit.audit.constraintDependencies.some((dependency) => constraints.get(dependency.constraintId) !== dependency.constraintDigest);
+        const taskInputChanged = audit.audit.snapshot.taskInputDigest !== qualification.qualification.taskInputDigest;
+        if (audit.audit.snapshot.nonConstraintInputDigest !== qualification.qualification.nonConstraintInputDigest
+          || constraintsChanged
+          || (taskInputChanged && !constraintsChanged)
+          || (taskInputChanged && !qualificationCandidateSnapshotMatches(audit.audit, qualification.qualification))) qualificationStaleArtifacts.push(name);
+      }
+    }
     const reviews: LifecycleFacts['reviews'] = {};
     const reviewedInputs: NonNullable<LifecycleFacts['reviewedInputs']> = {};
     for (const family of ['review-analysis', 'review-plan', 'review-code'] as const) {
@@ -249,7 +305,11 @@ function buildLifecycleFacts(taskDir: string, content: string, taskState = 'acti
       taskState, currentStep: String(metadata.current_step ?? ''), artifacts, reviews,
       staleArtifacts, reviewedInputs, artifactHashes,
       invalidation: invalidation.document, reworkIntents: rework.intents,
-      unresolvedLedger, executionBusy: executionBusy || hasOpenLifecycleExecution(content), recommendedAction: null
+      unresolvedLedger,
+      executionBusy: executionBusy || hasOpenLifecycleExecution(content),
+      recommendedAction: null,
+      qualificationStale: qualificationStaleArtifacts.length > 0,
+      qualificationStaleArtifacts
     };
     facts.recommendedAction = recommendNext(facts).action;
     return { ok: true, facts };