Implement Convergence Loop (iterate until rendered output matches expected.swift)

[leogdion]

Phase

Phase 5: Main Orchestration (Part 2)

Specification

Wrap the single-shot generation pipeline (#120) in a convergence loop: build the generated library, render dsl.swift against it, diff the rendered Swift against expected.swift, and re-prompt Claude with the build errors or diff until the output matches or --max-iterations is reached. This is the core purpose of the analyze feature: continually fix the SyntaxKit code until the DSL renders the intended result.

Architecture note: verification requires subprocess execution (swift build, compile-and-run rendering like skit run — the Swift JIT cannot load the dylib). Per the project's SDK/CLI boundary, Subprocess stays in the skit target: AiSTKit defines a LibraryVerifying protocol and the loop driver; skit supplies the Subprocess-backed implementation, mirroring how Runner works today.

Consider using swift-service-lifecycle to run the loop: it is a long-running process (multiple API calls, builds, and renders per run), and ServiceLifecycle's graceful-shutdown handling would cancel in-flight API calls/subprocesses, clean up temporary build artifacts, and report partial progress (iterations completed, last diff) on Ctrl-C. Evaluate during implementation whether the dependency is worth it versus plain structured concurrency with withTaskCancellationHandler.

Acceptance Criteria

• LibraryVerifying protocol defined in AiSTKit with no Subprocess dependency
• Subprocess-backed verifier in skit: builds the generated library, renders dsl.swift against it via compile-and-run, captures build errors and rendered output
• ConvergenceLoop drives generate → verify → re-prompt cycles, capped by --max-iterations (default 3)
• Re-prompt includes swift build errors or a unified diff of rendered vs expected output
• skit analyze reports converged/diverged status and iteration count; non-zero exit on divergence
• Diff comparison normalizes whitespace/formatting before declaring a mismatch
• Code follows one-type-per-file organization

Dependencies

• Depends on: Implement SyntaxKitAnalyzer Orchestration #120

Files to Create/Modify

• Sources/AiSTKit/LibraryVerifying.swift
• Sources/AiSTKit/VerificationResult.swift
• Sources/AiSTKit/ConvergenceLoop.swift
• Sources/AiSTKit/PromptTemplate+Feedback.swift
• Sources/skit/SubprocessLibraryVerifier.swift
• Sources/skit/Skit+Analyze.swift

Related Documentation

• skit-analyze-plan.md