IdeaAMBIG 2026: Tolok Ukur Codification Readiness, Anatomi Defect Localization, dan Kegagalan Kritis AI Coding Agents pada Spesifikasi Riset

// IdeaAMBIG Codification-Readiness Verification & Defect Localization Engine
// Berdasarkan Prinsip Arsitektur arXiv:2609.10539 (Ma, Zhao, Wu, Patwardhan, Cohan / Yale NLP, 2026)
// Mengimplementasikan Taksonomi 3-Tingkat / 10-Kategori Cacat, Pre-Execution Readiness Gate,
// dan Clarification Action Protocol untuk Mencegah Halusinasi pada AI Coding Agents.

export type DefectLevel1 = 'AMBIGUITY' | 'INCOMPLETENESS' | 'INCONSISTENCY';

export type DefectLevel2 =
  | 'AMBIGUOUS_DEFINITION'
  | 'AMBIGUOUS_PROCEDURE'
  | 'MISSING_METHOD_PROCEDURE'
  | 'MISSING_CONFIGURATION_PROTOCOL'
  | 'MISSING_MODEL_STRUCTURE'
  | 'MISSING_EVALUATION_SPECIFICATION'
  | 'MISSING_DATA_SPECIFICATION'
  | 'CONFLICTING_OBJECTIVE'
  | 'CONFLICTING_MODEL_DESIGN'
  | 'CONFLICTING_FORMAL_DEFINITION';

export interface SpecificationSpan {
  startOffset: number;
  endOffset: number;
  snippetText: string;
}

export interface DefectAnnotation {
  id: string;
  categoryL1: DefectLevel1;
  categoryL2: DefectLevel2;
  rationale: string;
  evidenceSpan?: SpecificationSpan;
  severity: 'BLOCKING' | 'DEGRADED_FIDELITY' | 'COSMETIC';
}

export interface ClarificationAction {
  defectId: string;
  targetSubsystem: string;
  targetedInquiry: string;
  suggestedOptions: string[];
  oracleGroundingRequirement: string;
}

export interface ReadinessEvaluationResult {
  specificationId: string;
  verdict: 'READY' | 'NOT_READY';
  confidence: number;
  detectedDefects: DefectAnnotation[];
  requiredClarifications: ClarificationAction[];
  allowAutonomousExecution: boolean;
}

/**
 * 1. Codification Readiness Inspector Gate
 * Menolak eksekusi otomatis ke coding agent jika terdapat celah metodologis pemblokir (blocking gaps)
 */
export class CodificationReadinessGate {
  private readonly blockingDefectTypes: Set<DefectLevel2> = new Set([
    'MISSING_METHOD_PROCEDURE',
    'MISSING_MODEL_STRUCTURE',
    'CONFLICTING_OBJECTIVE',
    'CONFLICTING_MODEL_DESIGN',
    'AMBIGUOUS_PROCEDURE',
  ]);

  /**
   * Mengaudit teks spesifikasi ide riset atau rekayasa sebelum diproses oleh LLM Coding Agent
   */
  public auditSpecification(
    specId: string,
    specText: string,
    inspectedDefects: DefectAnnotation[]
  ): ReadinessEvaluationResult {
    const blockingDefects = inspectedDefects.filter(
      (d) => this.blockingDefectTypes.has(d.categoryL2) || d.severity === 'BLOCKING'
    );

    const isReady = blockingDefects.length === 0;
    const requiredClarifications: ClarificationAction[] = blockingDefects.map((defect) =>
      this.synthesizeClarificationAction(defect)
    );

    return {
      specificationId: specId,
      verdict: isReady ? 'READY' : 'NOT_READY',
      confidence: isReady ? 0.95 : 0.88,
      detectedDefects: inspectedDefects,
      requiredClarifications,
      allowAutonomousExecution: isReady,
    };
  }

  /**
   * 2. Clarification Action Generator (Task 3 pada IdeaAMBIG)
   * Menyusun pertanyaan terstruktur untuk mengisi parameter yang hilang tanpa asumsi sepihak
   */
  private synthesizeClarificationAction(defect: DefectAnnotation): ClarificationAction {
    switch (defect.categoryL2) {
      case 'MISSING_METHOD_PROCEDURE':
        return {
          defectId: defect.id,
          targetSubsystem: 'Algorithm / Pipeline Kernel',
          targetedInquiry: `Metode komputasi utama tidak memiliki spesifikasi langkah diskret: ${defect.rationale}`,
          suggestedOptions: [
            'Berikan rumus formal atau pseudocode eksplisit',
            'Cantumkan referensi ke implementasi baseline kanonikal',
          ],
          oracleGroundingRequirement: 'Wajib diverifikasi terhadap referensi paper atau source code resmi.',
        };

      case 'MISSING_CONFIGURATION_PROTOCOL':
        return {
          defectId: defect.id,
          targetSubsystem: 'Hyperparameter & Training Setup',
          targetedInquiry: `Konfigurasi runtime (learning rate, batch size, threshold) tidak terdefinisi: ${defect.rationale}`,
          suggestedOptions: ['Spesifikasikan tabel konfigurasi lengkap', 'Gunakan profil default teruji'],
          oracleGroundingRequirement: 'Mencegah deviasi akurasi model hilir.',
        };

      case 'CONFLICTING_OBJECTIVE':
        return {
          defectId: defect.id,
          targetSubsystem: 'Loss Function & Optimization Target',
          targetedInquiry: `Terdapat kontradiksi antara objektif formulasi formal dan narasi teks: ${defect.rationale}`,
          suggestedOptions: ['Pilih formulasi Loss A', 'Pilih formulasi Loss B dengan pembobotan'],
          oracleGroundingRequirement: 'Menghindari kegagalan konvergensi training.',
        };

      default:
        return {
          defectId: defect.id,
          targetSubsystem: 'General Method Specification',
          targetedInquiry: `Kesenjangan metodologis terdeteksi pada ${defect.categoryL2}: ${defect.rationale}`,
          suggestedOptions: ['Klarifikasi definisi operasional'],
          oracleGroundingRequirement: 'Mencegah asumsi halusinatif coding agent.',
        };
    }
  }
}

/**
 * 3. Autonomous Execution Harness Dispatcher
 * Memblokir loop coding agent jika status spesifikasi NOT_READY untuk mencegah 'unsupported assumptions'
 */
export async function executeAgenticWorkflow(
  specText: string,
  gate: CodificationReadinessGate,
  defectDetector: (text: string) => Promise<DefectAnnotation[]>,
  agentExecutor: (text: string) => Promise<{ codeFiles: string[] }>
): Promise<{ status: 'SUCCESS' | 'CLARIFICATION_REQUIRED'; artifacts?: string[]; issues?: ClarificationAction[] }> {
  // Tahap 1: Deteksi & Lokalisasi Cacat
  const detectedDefects = await defectDetector(specText);

  // Tahap 2: Evaluasi Kesiapan (Readiness Gate)
  const audit = gate.auditSpecification('spec-' + Date.now(), specText, detectedDefects);

  if (!audit.allowAutonomousExecution) {
    console.warn('[GATE_VETO] Spesifikasi NOT_READY. Eksekusi coding agent dibatalkan demi integritas kode.');
    return {
      status: 'CLARIFICATION_REQUIRED',
      issues: audit.requiredClarifications,
    };
  }

  // Tahap 3: Eksekusi Kode jika spesifikasi READY
  console.log('[GATE_PERMIT] Spesifikasi lolos audit. Melanjutkan ke Autonomous Coding Agent...');
  const build = await agentExecutor(specText);
  return {
    status: 'SUCCESS',
    artifacts: build.codeFiles,
  };
}