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
```

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.

## Framework Detection

Framework detection is project-agnostic: the skill walks the worktree, inspects config files, and selects the correct test command. No language or framework is special-cased above another. The full detection table lives in [references/frameworks.md](references/frameworks.md). In summary: detection reads the project manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, or `.cleo/project-context.json#testing.command`) and selects one of: `vitest`, `jest`, `mocha`, `pytest`, `unittest`, `go-test`, `cargo-test`, `rspec`, `phpunit`, `bats`, `other`.

## Convergence Criteria

The loop has converged when **all** of the following hold:

- Every MUST requirement in the task's linked specification has at least one passing test (spec-to-test traceability complete).
- `testsFailed == 0`, `testsRun > 0`, and `testsPassed == testsRun`.
- Project linter reports zero errors (warnings are allowed).
- Type checker reports zero errors.
- CI-equivalent local commands return zero (e.g., `pnpm run build`, `cargo build`, `go build ./...`).
- No new runtime errors were observed during the test run.

A loop that makes tests pass by deleting assertions, narrowing scope, or mocking the thing under test is **not** converged — that is a spec violation dressed up as a green run. See [references/loop-anatomy.md](references/loop-anatomy.md) for worked examples.

## Branch Discipline

Before iteration 1, the skill MUST verify the current branch:

```bash
branch=$(git branch --show-current)
if [[ "$branch" == "main" || "$branch" == "master" || "$branch" == "trunk" ]]; then
    echo "Refusing to run IVT loop on protected branch: $branch"
    exit 65   # HANDOFF_REQUIRED: ask HITL for a feature branch
fi
```

The loop is destructive in the sense that it rewrites code on failed iterations. It MUST run on a feature branch or worktree. If the user invoked it on a protected branch, stop and request a feature branch.

## Escalation on Non-Convergence

When the loop exhausts `MAX_ITERATIONS` without converging, the skill MUST:

1. Write the manifest entry with `ivtLoopConverged: false` and the iteration count.
2. Record the last diagnostic output in `key_findings`.
3. Exit with code 65 (`HANDOFF_REQUIRED`).
4. Leave the worktree in its last state — do **not** revert.

The human reviewer picks up the worktree, reads the diagnostics, and either raises the iteration cap, rewrites the spec, or manually corrects the implementation before rerunning the skill. The full escalation handoff protocol is in [references/escalation.md](references/escalation.md).

## Integration

Record the loop outcome through `cleo check protocol`:

```bash
# Success case: loop converged on iteration 3.
cleo check protocol \
  --protocolType testing \
  --framework vitest \
  --testsRun 142 \
  --testsPassed 142 \
  --testsFailed 0 \
  --ivtLoopConverged true \
  --ivtLoopIterations 3

# Failure case: loop exhausted iterations, HITL escalation.
cleo check protocol \
  --protocolType testing \
  --framework pytest \
  --testsRun 87 \
  --testsPassed 84 \
  --testsFailed 3 \
  --ivtLoopConverged false \
  --ivtLoopIterations 5
```

Exit code 0 = loop converged and protocol is valid. Exit code 65 = `HANDOFF_REQUIRED` (non-convergence).

This skill MUST also chain a validation check against the spec before its own testing check:

```bash
cleo check protocol \
  --protocolType validation \
  --specMatchConfirmed true \
  --testSuitePassed true \
  --protocolComplianceChecked true
```

## Anti-Patterns

| Pattern | Problem | Solution |
|---------|---------|----------|
| Hardcoding vitest or jest | Violates IVT-005; breaks on any non-JS project | Walk the worktree and pick the framework per project |
| Running the loop on main/master | Violates IVT-006; pollutes shared branch | Check `git branch --show-current` and refuse protected branches |
| No iteration cap | Infinite loop on unreachable convergence; context burn | Enforce `MAX_ITERATIONS` (default 5); escalate to HITL on exhaustion |
| Deleting assertions to force green | Tests pass but the spec is not met | The skill requires spec-to-test traceability; gaps block convergence |
| Skipping the validation phase | Lint or type errors slip through | The loop MUST run lint and type check before the test phase every iteration |
| Treating testing as "just run the tests" | Misses the loop; one-shot runs are not compliant | Testing is a loop, not a single call; record `ivtLoopIterations` |
| Exiting without writing the manifest | Downstream skills cannot see the outcome | Always write the manifest entry — converged or not — before exiting |
| Reverting the worktree on escalation | Destroys diagnostic evidence | Leave the failed state; the human reviewer needs it |

## Critical Rules Summary

1. Detect the test framework from the worktree before iterating; never hardcode.
2. Cap iterations at `MAX_ITERATIONS` (default 5); escalate on exhaustion.
3. Every MUST in the spec MUST map to a passing test before declaring convergence.
4. Each iteration runs all three phases: Implement, Validate, Test.
5. Never run on `main`, `master`, or `trunk` — stop and request a feature branch.
6. Record `framework`, `testsRun`, `testsPassed`, `testsFailed`, `ivtLoopConverged`, `ivtLoopIterations` in the manifest.
7. On non-convergence, exit 65 and leave the worktree untouched.
8. Validate every run via `cleo check protocol --protocolType testing`.