ct-ivt-looper

IVT Looper

Overview

Runs an autonomous Implement-then-Validate-then-Test loop against any git worktree, detects the test framework in use, and iterates until the implementation converges on its specification. This skill is the autonomous compliance layer: no task ships, no release runs, and no PR opens until the loop has recorded a converged result to the manifest.

Core Principle

The loop converges on the spec, not on 'tests pass'. Passing tests that don't cover the spec is a failure.

Immutable Constraints

ID	Rule	Enforcement
IVT-001	Test framework MUST be detected or declared before the loop starts.	validateTestingProtocol rejects entries without a framework; deducts 20 from score.
IVT-002	Loop MUST cap iterations at MAX_ITERATIONS (default 5).	Hard counter in the loop; unreachable convergence forces HITL escalation.
IVT-003	Every MUST requirement in the spec MUST map to at least one passing test.	Spec-to-test traceability matrix; gaps block convergence.
IVT-004	Final manifest entry MUST record framework, testsRun, testsPassed, testsFailed, ivtLoopConverged, ivtLoopIterations.	validateTestingProtocol requires these fields; ivtLoopConverged: false fails validation.
IVT-005	Framework detection MUST NOT be hardcoded to one project's tooling.	Detection walks the project tree; no vitest/jest-only code paths.
IVT-006	Loop MUST NOT run on the main branch.	Check git branch --show-current; stop if on main/master/trunk.
IVT-007	Non-convergence after MAX_ITERATIONS MUST escalate to HITL (exit code 65).	Agent stops, writes manifest with ivtLoopConverged: false, exits.
IVT-008	Final manifest entry MUST set agent_type: "testing".	Validator rejects any other value.

The IVT Loop

load_spec(task_id)                         # read acceptance criteria from canon
detect_framework(worktree)                 # see references/frameworks.md
branch_check()                             # abort if on main/master/trunk
iteration = 0

while iteration < MAX_ITERATIONS:          # IVT-002
    iteration += 1

    # ----- I : Implement -----
    apply_patch(current_diff)              # patch generated by the implementer
    ensure_provenance_tags(new_code)       # IMPL-003 tags on new functions

    # ----- V : Validate -----
    lint_result = run_project_linter()
    type_result = run_type_checker()       # tsc / mypy / go vet / rustc
    if lint_result.failed or type_result.failed:
        regenerate_fix_for(lint_result, type_result)
        continue                           # back to top, same iteration count

    # ----- T : Test -----
    test_result = run_framework_tests()    # framework-specific command
    trace = spec_to_test_trace(spec)       # IVT-003: every MUST has a test
    if test_result.all_passed and trace.complete:
        write_manifest(
            framework=framework,
            iterations=iteration,
            converged=True,
            agent_type="testing",
        )
        return CONVERGED                   # exit loop, exit skill with code 0

    # ----- Analyze and regenerate fix -----
    failure = diagnose(test_result, trace)
    current_diff = regenerate_fix_for(failure)

# MAX_ITERATIONS reached without convergence
write_manifest(
    framework=framework,
    iterations=MAX_ITERATIONS,
    converged=False,
    agent_type="testing",
)
escalate_to_hitl()                         # IVT-007: exit code 65