/ct-ivt-looper

name: ct-ivt-looper
description: "Runs a project-agnostic autonomous Implement-then-Validate-then-Test compliance loop on any git worktree. Detects the project's test framework (vitest, jest, mocha, pytest, unittest, go-test, cargo-test, rspec, phpunit, bats, or other) and iterates until the implementation satisfies its specification, recording convergence metrics to the manifest. Use when given an implementation task that must ship verified: the IVT loop is the autonomous compliance layer enforced before any release or PR. Triggers on phrases like 'implement and verify', 'run the IVT loop', 'ship this task', 'complete implementation with tests', 'verify against spec', or any implementation task with acceptance criteria. Works in any git worktree regardless of language or framework, never hardcoded to one project's tooling."
protocol: testing
adrRefs:
  - ADR-051
  - ADR-061
metadata:
  version: 1.0.3
  tier: on-demand
  install: harness
  covers:
    - packages/core/src/validation/protocols/cant/testing.cant
    - packages/core/src/validation/protocols/protocols-markdown/testing.md
  loomStage: testing
  lastReviewed: 2026-10-01
  stability: stable

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

The loop is a *single* stage from the lifecycle's point of view. Implement, Validate, and Test are not three separate tasks — they are three phases of one autonomous run that either converges or escalates.

Out of Scope (T9675)

`ct-ivt-looper` operates on the **`testing`** LOOM lifecycle stage (stage 8). It performs the **dynamic** Implement-then-Validate-then-Test loop with framework detection and iterate-until-green convergence semantics.

This skill does NOT:

• Audit static artifacts for schema/compliance/RFC-2119 keyword usage, ADR-document structure, or JSON Schema conformance. Those belong to **`ct-validator`** at the `validation` stage (stage 7). When the question is "is this document/manifest well-formed?" rather than "does this code converge on its spec?", chain to `ct-validator` rather than expanding scope here.
• Promote a green loop to release. Release sequencing belongs to **`ct-release-orchestrator`** at stage 9.

Chain handoffs

| Direction | When | Handoff | |---|---|---| | `ct-ivt-looper` → `ct-validator` | Loop converged; need to audit the resulting artifacts (e.g. final manifest, spec back-references) against schema/compliance | Emit the convergence manifest entry, then dispatch the `validation` stage | | `ct-validator` → `ct-ivt-looper` | Spec