@fitlab-ai/agent-infra 0.9.12 → 0.9.14

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

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { ArtifactSchemaFamily } from './artifact-schema.ts';
+
+type ArtifactRepairIntent = Readonly<{
+  version: 1;
+  taskId: string;
+  family: ArtifactSchemaFamily;
+  artifact: string;
+  state: 'awaiting-repair' | 'passed' | 'consumed';
+  baselineSemanticDigest: string | null;
+  artifactSha256: string;
+  semanticDigest: string;
+}>;
+
+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 isArtifactRepairIntent(value: unknown): value is ArtifactRepairIntent {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const intent = value as Record<string, unknown>;
+  return intent.version === 1
+    && typeof intent.taskId === 'string' && /^TASK-\d{8}-\d{6}$/.test(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', 'passed', 'consumed'].includes(String(intent.state))
+    && (intent.baselineSemanticDigest === null || (typeof intent.baselineSemanticDigest === 'string' && /^[a-f0-9]{64}$/.test(intent.baselineSemanticDigest)))
+    && typeof intent.artifactSha256 === 'string' && /^[a-f0-9]{64}$/.test(intent.artifactSha256)
+    && typeof intent.semanticDigest === 'string' && /^[a-f0-9]{64}$/.test(intent.semanticDigest)
+    && (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;
+}
+
+function writeArtifactRepairIntent(repoRoot: string, value: ArtifactRepairIntent): 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 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;
+  }
+}
+
+export { readArtifactRepairIntent, writeArtifactRepairIntent };
+export type { ArtifactRepairIntent };

package/lib/task/artifact-schema.ts

@@ -0,0 +1,192 @@
+type ArtifactFamily =
+  | 'analysis'
+  | 'review-analysis'
+  | 'plan'
+  | 'review-plan'
+  | 'code'
+  | 'review-code'
+  | 'manual-validation'
+  | 'validation-run'
+  | 'pr-review';
+
+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;
+}>;
+
+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 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 roundMatch = input.artifact.match(/-r(\d+)\.md$/);
+  const round = roundMatch ? Number(roundMatch[1]) : 1;
+  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_FAMILY_CATALOG,
+  ARTIFACT_SCHEMAS,
+  getArtifactSchema,
+  renderArtifactSkeleton
+};
+export type {
+  ArtifactFamily,
+  ArtifactFamilySpec,
+  ArtifactLocale,
+  ArtifactSchema,
+  ArtifactSchemaFamily,
+  ArtifactSection,
+  ArtifactSkeletonInput
+};

package/lib/task/capabilities.ts

@@ -0,0 +1,331 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import type { InvalidationDocument } from './invalidation.ts';
+import { invalidationBlocks, isArtifactInvalidated, parseInvalidationDocument } from './invalidation.ts';
+import { receiptForOutput } from './artifact-receipts.ts';
+import { parseTypedTaskFrontmatter } from './frontmatter.ts';
+import { parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from './ledger.ts';
+import { parseReviewSummary, resolveCanonicalVerdict } from './review-artifacts.ts';
+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'
+  | 'code' | 'review-code' | 'manual-validation' | 'validation-run';
+type TriggerInitiator = 'human' | 'model' | 'orchestrator';
+type TriggerReason = 'user-request' | 'new-requirement' | 'upstream-fact-doubt' | 'review-finding' | 'retry' | 'validation-rerun';
+type ExplicitTrigger = {
+  initiator: TriggerInitiator;
+  requestId: string;
+  requestedAction: LifecycleAction;
+  reasonCode: TriggerReason;
+  sourceFinding?: string;
+  sourceArtifact?: string;
+  sourceSha256?: string;
+  implementationInput?: string;
+  /** False marks the ordinary recommended workflow event; it is not an authorization fact. */
+  explicitRequest?: boolean;
+};
+type LifecycleFacts = {
+  taskState: string;
+  currentStep: string;
+  artifacts: Partial<Record<LifecycleAction, readonly string[]>>;
+  staleArtifacts?: Partial<Record<LifecycleAction, readonly string[]>>;
+  reviewedInputs?: Partial<Record<'review-analysis' | 'review-plan' | 'review-code', string>>;
+  artifactHashes: Readonly<Record<string, string>>;
+  reviews: Partial<Record<'review-analysis' | 'review-plan' | 'review-code', 'approved' | 'changes-requested' | 'rejected'>>;
+  invalidation: InvalidationDocument;
+  reworkIntents?: readonly ReworkIntent[];
+  unresolvedLedger: Record<'analysis' | 'plan' | 'code', number>;
+  executionBusy: boolean;
+  recommendedAction?: LifecycleAction | null;
+  qualificationStale?: boolean;
+  qualificationStaleArtifacts?: readonly string[];
+};
+type CapabilityResult = {
+  allowed: boolean;
+  reasonCode: string;
+  evidence: readonly string[];
+};
+type LifecycleRecommendation = {
+  action: LifecycleAction | null;
+  reasonCode: string;
+  evidence: readonly string[];
+};
+type LifecycleFactsResult =
+  | { ok: true; facts: LifecycleFacts }
+  | { ok: false; code: 'TASK_CAPABILITY_FACTS_INVALID'; message: string };
+
+const REASONS = new Set<TriggerReason>([
+  'user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'retry', 'validation-rerun'
+]);
+
+function deny(reasonCode: string, ...evidence: string[]): CapabilityResult {
+  return { allowed: false, reasonCode, evidence };
+}
+
+function allow(...evidence: string[]): CapabilityResult {
+  return { allowed: true, reasonCode: 'CAPABILITY_ALLOWED', evidence };
+}
+
+function hasArtifact(facts: LifecycleFacts, action: LifecycleAction): boolean {
+  return (facts.artifacts[action]?.length ?? 0) > 0;
+}
+
+function canStart(action: LifecycleAction, facts: LifecycleFacts, trigger: ExplicitTrigger): CapabilityResult {
+  if (!trigger || trigger.requestedAction !== action) return deny('TRIGGER_ACTION_MISMATCH', `requested=${trigger?.requestedAction ?? 'missing'}`);
+  if (!trigger.requestId || !trigger.requestId.trim()) return deny('TRIGGER_REQUEST_ID_REQUIRED');
+  if (!REASONS.has(trigger.reasonCode)) return deny('TRIGGER_REASON_INVALID');
+  if (trigger.sourceArtifact && !trigger.sourceSha256) return deny('SOURCE_ARTIFACT_HASH_REQUIRED');
+  if (trigger.sourceSha256 && !trigger.sourceArtifact) return deny('SOURCE_ARTIFACT_REQUIRED');
+  if (trigger.sourceArtifact && trigger.sourceSha256) {
+    const actual = facts.artifactHashes[trigger.sourceArtifact];
+    if (!actual) return deny('SOURCE_ARTIFACT_MISSING', trigger.sourceArtifact);
+    if (actual !== trigger.sourceSha256) return deny('SOURCE_ARTIFACT_HASH_MISMATCH', trigger.sourceArtifact);
+  }
+  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;
+  if (action === 'analysis') {
+    if (!implicit || hasArtifact(facts, 'analysis') || facts.recommendedAction === 'analysis') return allow('analysis-capability');
+    return deny('ANALYSIS_REQUEST_REQUIRES_EXPLICIT_TRIGGER');
+  }
+  if (action === 'review-analysis') {
+    return hasArtifact(facts, 'analysis') ? allow('analysis-artifact') : deny('ANALYSIS_ARTIFACT_REQUIRED');
+  }
+  if (action === 'plan') {
+    if (!hasArtifact(facts, 'review-analysis')) return deny('ANALYSIS_REVIEW_REQUIRED');
+    if (!reviewMatchesLatest(facts, 'analysis', 'review-analysis')) return deny('ANALYSIS_REVIEW_NOT_LATEST');
+    if (facts.reviews['review-analysis'] !== 'approved') return deny('ANALYSIS_REVIEW_NOT_APPROVED');
+    if (facts.unresolvedLedger.analysis > 0) return deny('ANALYSIS_LEDGER_BLOCKED', `unresolved=${facts.unresolvedLedger.analysis}`);
+    return allow('analysis-review-approved');
+  }
+  if (action === 'review-plan') {
+    return hasArtifact(facts, 'plan') ? allow('plan-artifact') : deny('PLAN_ARTIFACT_REQUIRED');
+  }
+  if (action === 'code') {
+    if (trigger.implementationInput) {
+      if (!hasArtifact(facts, 'review-code')) return deny('CODE_REVIEW_REQUIRED');
+      if (!reviewMatchesLatest(facts, 'code', 'review-code')) return deny('CODE_REVIEW_NOT_LATEST');
+      if (facts.reviews['review-code'] !== 'approved') return deny('CODE_REVIEW_NOT_APPROVED');
+      return allow('implementation-input');
+    }
+    if (!hasArtifact(facts, 'review-plan')) return deny('PLAN_REVIEW_REQUIRED');
+    if (!reviewMatchesLatest(facts, 'plan', 'review-plan')) return deny('PLAN_REVIEW_NOT_LATEST');
+    if (facts.reviews['review-plan'] !== 'approved') return deny('PLAN_REVIEW_NOT_APPROVED');
+    if (facts.unresolvedLedger.plan > 0) return deny('PLAN_LEDGER_BLOCKED', `unresolved=${facts.unresolvedLedger.plan}`);
+    return allow('plan-review-approved');
+  }
+  if (action === 'review-code') {
+    return hasArtifact(facts, 'code') ? allow('code-artifact') : deny('CODE_ARTIFACT_REQUIRED');
+  }
+  if (action === 'manual-validation' || action === 'validation-run') {
+    if (!hasArtifact(facts, 'review-code')) return deny('CODE_REVIEW_REQUIRED');
+    if (!reviewMatchesLatest(facts, 'code', 'review-code')) return deny('CODE_REVIEW_NOT_LATEST');
+    if (facts.reviews['review-code'] !== 'approved') return deny('CODE_REVIEW_NOT_APPROVED');
+    if (facts.unresolvedLedger.code > 0) return deny('CODE_LEDGER_BLOCKED', `unresolved=${facts.unresolvedLedger.code}`);
+    return allow('code-review-approved');
+  }
+  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;
+}
+
+function reviewedInputName(content: string, expectedFamily: 'analysis' | 'plan' | 'code'): string | null {
+  const header = content.split(/\r?\n/).findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
+  if (header < 0) return null;
+  const referenceBlock = content.split(/\r?\n/).slice(header, header + 12).join('\n');
+  const expected = new RegExp('`' + expectedFamily + '(?:-r[2-9]|-r[1-9]\\d+)?\\.md`');
+  return expected.exec(referenceBlock)?.[0].slice(1, -1) ?? null;
+}
+
+function reviewMatchesLatest(facts: LifecycleFacts, source: 'analysis' | 'plan' | 'code', review: 'review-analysis' | 'review-plan' | 'review-code'): boolean {
+  const latestSource = latestArtifact(facts.artifacts[source] ?? []);
+  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'] };
+  if (!hasArtifact(facts, 'review-analysis') || !reviewMatchesLatest(facts, 'analysis', 'review-analysis')) {
+    return { action: 'review-analysis', reasonCode: 'ANALYSIS_REVIEW_MISSING', evidence: ['analysis review does not bind the latest analysis artifact'] };
+  }
+  if (facts.reviews['review-analysis'] !== 'approved' || facts.unresolvedLedger.analysis > 0) {
+    return { action: 'analysis', reasonCode: 'ANALYSIS_REWORK_REQUIRED', evidence: ['analysis review or ledger is not clear'] };
+  }
+  if (!hasArtifact(facts, 'plan')) return { action: 'plan', reasonCode: 'PLAN_ARTIFACT_MISSING', evidence: ['plan artifact is absent'] };
+  if (!hasArtifact(facts, 'review-plan') || !reviewMatchesLatest(facts, 'plan', 'review-plan')) {
+    return { action: 'review-plan', reasonCode: 'PLAN_REVIEW_MISSING', evidence: ['plan review does not bind the latest plan artifact'] };
+  }
+  if (facts.reviews['review-plan'] !== 'approved' || facts.unresolvedLedger.plan > 0) {
+    return { action: 'plan', reasonCode: 'PLAN_REWORK_REQUIRED', evidence: ['plan review or ledger is not clear'] };
+  }
+  if (!hasArtifact(facts, 'code')) return { action: 'code', reasonCode: 'CODE_ARTIFACT_MISSING', evidence: ['code artifact is absent'] };
+  if (!hasArtifact(facts, 'review-code') || !reviewMatchesLatest(facts, 'code', 'review-code')) {
+    return { action: 'review-code', reasonCode: 'CODE_REVIEW_MISSING', evidence: ['code review does not bind the latest code artifact'] };
+  }
+  if (facts.reviews['review-code'] !== 'approved') {
+    return { action: 'code', reasonCode: 'CODE_REWORK_REQUIRED', evidence: ['code review or ledger is not clear'] };
+  }
+  return { action: null, reasonCode: 'LIFECYCLE_REVIEWED', evidence: ['latest code review is approved'] };
+}
+
+function buildLifecycleFacts(taskDir: string, content: string, taskState = 'active', executionBusy = false): LifecycleFactsResult {
+  try {
+    const metadata = parseTypedTaskFrontmatter(content);
+    const invalidation = parseInvalidationDocument(content);
+    if (!invalidation.ok) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: invalidation.message };
+    const rework = parseReworkIntentDocument(content);
+    if (!rework.ok) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: rework.message };
+    const ledger = parseLedgerDocument(content);
+    if (ledger.present) {
+      const invalid = validateLedgerRows(ledger.rows);
+      if (invalid) return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: invalid.message };
+    }
+    const files = fs.readdirSync(taskDir).filter((name) => {
+      if (!name.endsWith('.md')) return false;
+      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 activeFiles = files.filter((name) => {
+      const family = familyFor(name);
+      return !family || !isArtifactInvalidated(invalidation.document, family, name);
+    });
+    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))
+      ])
+    ) 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))
+      ])
+    ) 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 Object.keys(artifactFamilies) as Array<keyof typeof 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) {
+      const latest = latestArtifact(artifacts[family] ?? []);
+      if (!latest) continue;
+      const reviewContent = fs.readFileSync(path.join(taskDir, latest), 'utf8');
+      const expectedFamily = family === 'review-analysis' ? 'analysis' : family === 'review-plan' ? 'plan' : 'code';
+      const input = reviewedInputName(reviewContent, expectedFamily);
+      const receipt = input ? receiptForOutput(content, latest) : null;
+      if (input && receipt?.input === input && artifactHashes[input] === receipt.inputSha256) reviewedInputs[family] = input;
+      const parsed = parseReviewSummary(reviewContent);
+      if (!parsed.ok) continue;
+      const verdict = resolveCanonicalVerdict(parsed.summary);
+      if (verdict.ok) reviews[family] = verdict.verdict === 'Approved' ? 'approved' : verdict.verdict === 'Changes Requested' ? 'changes-requested' : 'rejected';
+    }
+    const unresolvedLedger = { analysis: 0, plan: 0, code: 0 };
+    if (ledger.present) {
+      for (const stage of ['analysis', 'plan', 'code'] as const) unresolvedLedger[stage] = summarizeLedgerStage(ledger.rows, stage).unresolved.length;
+    }
+    const facts: LifecycleFacts = {
+      taskState, currentStep: String(metadata.current_step ?? ''), artifacts, reviews,
+      staleArtifacts, reviewedInputs, artifactHashes,
+      invalidation: invalidation.document, reworkIntents: rework.intents,
+      unresolvedLedger,
+      executionBusy: executionBusy || hasOpenLifecycleExecution(content),
+      recommendedAction: null,
+      qualificationStale: qualificationStaleArtifacts.length > 0,
+      qualificationStaleArtifacts
+    };
+    facts.recommendedAction = recommendNext(facts).action;
+    return { ok: true, facts };
+  } catch (error) {
+    return { ok: false, code: 'TASK_CAPABILITY_FACTS_INVALID', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+export { buildLifecycleFacts, canStart, recommendNext };
+export type { CapabilityResult, ExplicitTrigger, LifecycleAction, LifecycleFacts, LifecycleFactsResult, LifecycleRecommendation, TriggerInitiator, TriggerReason };