@cleocode/skills 2026.4.4 → 2026.4.6

package/skills/ct-ivt-looper/SKILL.md

@@ -0,0 +1,181 @@
+---
+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."
+---
+
+# 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`.

package/skills/ct-ivt-looper/manifest-entry.json

@@ -0,0 +1,30 @@
+{
+  "_comment": "CLEO-only metadata -- add to packages/skills/skills/manifest.json",
+  "name": "ct-ivt-looper",
+  "version": "1.0.0",
+  "tier": 2,
+  "token_budget": 10000,
+  "protocol": "testing",
+  "capabilities": {
+    "inputs": ["task-id", "spec-reference", "worktree-path"],
+    "outputs": ["manifest-entry", "ivt-convergence-report"],
+    "dispatch_triggers": [
+      "run the IVT loop",
+      "implement and verify",
+      "ship this task",
+      "verify against spec",
+      "complete implementation with tests"
+    ],
+    "compatible_subagent_types": ["general-purpose"],
+    "chains_to": ["ct-validator", "ct-release-orchestrator"],
+    "dispatch_keywords": {
+      "primary": ["ivt", "implement", "validate", "test"],
+      "secondary": ["converge", "framework", "spec", "iterate"]
+    }
+  },
+  "constraints": {
+    "max_context_tokens": 80000,
+    "requires_session": false,
+    "requires_epic": false
+  }
+}

package/skills/ct-ivt-looper/references/escalation.md

@@ -0,0 +1,91 @@
+# IVT Non-Convergence Escalation
+
+When the loop exhausts `MAX_ITERATIONS` without converging, the skill hands control back to a human reviewer. This file documents the hand-off contract.
+
+## When to Escalate
+
+Escalation fires on exactly one condition:
+
+```
+iteration == MAX_ITERATIONS && converged == false
+```
+
+Other failure modes — missing framework, protected branch, credential error — also exit with code 65, but they are **pre-loop** escalations. This document covers post-loop escalation only.
+
+## Manifest Entry on Escalation
+
+The escalation manifest entry MUST include:
+
+| Field | Value | Why |
+|-------|-------|-----|
+| `agent_type` | `"testing"` | IVT-008; every run, converged or not |
+| `framework` | detected framework | IVT-001 |
+| `testsRun` | final count | Evidence of the last attempt |
+| `testsPassed` | final count | — |
+| `testsFailed` | final count | — |
+| `ivtLoopConverged` | `false` | IVT-007 |
+| `ivtLoopIterations` | `MAX_ITERATIONS` | Shows exhaustion |
+| `key_findings` | diagnostic lines | Reviewer reads these first |
+
+Example:
+
+```json
+{
+  "agent_type": "testing",
+  "framework": "pytest",
+  "testsRun": 87,
+  "testsPassed": 84,
+  "testsFailed": 3,
+  "ivtLoopConverged": false,
+  "ivtLoopIterations": 5,
+  "key_findings": [
+    "tests/test_auth.py::test_expired_token failed on all 5 iterations",
+    "fix attempts alternated between re-raising and swallowing TokenExpiredError",
+    "spec clause SEC-003 not satisfied by any current test",
+    "worktree left at commit 3a2f1e9 on branch feature/auth-refresh"
+  ]
+}
+```
+
+`key_findings` is the most important field. The reviewer does not re-run the loop's diagnostics; they read the findings and decide which lever to pull.
+
+## Worktree State
+
+The skill MUST NOT revert the worktree on escalation. The reviewer needs:
+
+- The last patch that was attempted.
+- The last test output.
+- Any temporary files the loop created.
+- The current branch (as left by the loop).
+
+Reverting destroys all of this evidence and forces the reviewer to re-run the loop from scratch. Do not revert.
+
+## Reviewer Levers
+
+When a human reviewer picks up an escalated loop, they have four options:
+
+| Lever | When to use | Consequence |
+|-------|-------------|-------------|
+| **Raise the cap** | The loop was making progress but needed more iterations | Set `MAX_ITERATIONS` higher for this task; rerun the skill |
+| **Rewrite the spec** | A spec clause is impossible or contradictory | Update the spec, then rerun the loop; the trace will now match |
+| **Manual correction** | The spec is fine but the loop's fix generator is stuck | Apply a human patch, then rerun; the loop resumes from the corrected state |
+| **Abandon the task** | The work is no longer needed | Mark the task `cancelled`; no rerun |
+
+The skill does not pick a lever itself. Picking a lever is a human decision.
+
+## Rerun Semantics
+
+When the skill is re-invoked after an escalation, it MUST:
+
+1. Read the previous manifest entry for the task.
+2. Start a new iteration counter (the cap applies per invocation, not globally).
+3. Keep the worktree state; do not reset to a prior commit.
+4. Write a fresh manifest entry on completion — do not edit the old one.
+
+The previous manifest entry stays in the canon as the record of the failed attempt. The new entry sits alongside it. This preserves the history for post-mortems.
+
+## Escalation Is Not Failure
+
+A loop that converges in five iterations and a loop that escalates to HITL are both valid outcomes. Escalation is the mechanism by which the skill stays honest about its limits. Agents that hide non-convergence by spoofing convergence metrics are worse than agents that escalate cleanly.
+
+The only actual failure mode is: skipping the escalation, marking the task done, and letting uncovered spec clauses leak into a release.

package/skills/ct-ivt-looper/references/frameworks.md

@@ -0,0 +1,119 @@
+# Framework Detection
+
+The IVT loop is project-agnostic. The test framework MUST be detected from the worktree at loop start. This file is the authoritative detection table.
+
+## Detection Priority
+
+The detection walks these signals in order and stops at the first match:
+
+1. `.cleo/project-context.json#testing.framework` — explicit CLEO project hint.
+2. Language-specific manifest files (`package.json`, `pyproject.toml`, etc.).
+3. CI workflow files (`.github/workflows/*.yml`) — last-ditch signal.
+4. Fallback: `.cleo/project-context.json#testing.command` if nothing above matches, mark the framework as `other`.
+
+A project-context hint always wins. If the hint contradicts the manifest (e.g., `testing.framework: vitest` but `package.json` shows jest), the skill respects the hint and treats the discrepancy as a non-blocking warning.
+
+## Per-Framework Detection
+
+### vitest
+
+**Signal**: `package.json` has `vitest` in `devDependencies` or `vitest.config.{js,ts,mjs}` exists.
+
+**Test command**: `pnpm vitest run` (monorepo) or `npx vitest run` (single package). Use `--reporter=json` for structured parsing.
+
+**Edge case**: Projects with both vitest and jest installed (usually mid-migration) MUST be disambiguated by checking which config file exists. If both exist, read `.cleo/project-context.json#testing.framework` or fail with IVT-001.
+
+### jest
+
+**Signal**: `package.json` has `jest` in `devDependencies` or a `jest.config.{js,ts,cjs,mjs}` file, or a `jest` key in `package.json`.
+
+**Test command**: `npx jest --json` for structured output.
+
+**Edge case**: React Native projects sometimes use a jest preset without a top-level config. Detect via the `preset` key inside `package.json#jest`.
+
+### mocha
+
+**Signal**: `package.json` has `mocha` in `devDependencies` or `.mocharc.{js,json,cjs,yml}` exists.
+
+**Test command**: `npx mocha --reporter json`.
+
+**Edge case**: Mocha is often paired with chai/sinon; the test command stays the same. If `nyc` is present, prefer `npx nyc mocha --reporter json` to capture coverage in the same run.
+
+### pytest
+
+**Signal**: `pyproject.toml` has `[tool.pytest.ini_options]`, or a `pytest.ini` / `setup.cfg` with a `[tool:pytest]` section, or `pytest` appears in `requirements*.txt` or `pyproject.toml`'s test dependencies.
+
+**Test command**: `pytest --json-report --json-report-file=/tmp/pytest.json` (requires `pytest-json-report`) or fall back to `pytest -q` and parse the summary line.
+
+**Edge case**: Projects that use `tox` wrap pytest. Prefer `tox -e py` when a `tox.ini` is present and delegate parsing to the wrapped pytest run.
+
+### unittest
+
+**Signal**: No test runner in `pyproject.toml`/`requirements.txt`, but `tests/` contains files matching `test_*.py` with `unittest.TestCase` imports.
+
+**Test command**: `python -m unittest discover -s tests -p 'test_*.py'`.
+
+**Edge case**: unittest has no JSON reporter. The skill parses the stderr summary (`Ran N tests in T — OK` or `FAILED (errors=N)`).
+
+### go-test
+
+**Signal**: `go.mod` file at the repo root and at least one `*_test.go` file.
+
+**Test command**: `go test -json ./...` for structured output.
+
+**Edge case**: Projects that use Bazel (`BUILD.bazel`) wrap go test. Prefer `bazel test //...` when Bazel is present; fall back to `go test -json ./...` otherwise.
+
+### cargo-test
+
+**Signal**: `Cargo.toml` at the repo root.
+
+**Test command**: `cargo test -- --format json -Z unstable-options` (nightly toolchain) or `cargo test --message-format json` and parse the compile + test records.
+
+**Edge case**: Monorepo workspaces use `Cargo.toml` at the root with `[workspace]`. The test command runs all workspace members via `cargo test --workspace`. For single-crate runs, the skill MUST target the specific crate with `--package <name>`.
+
+### rspec
+
+**Signal**: `Gemfile` includes `rspec` or `rspec-rails`, or a `.rspec` file exists.
+
+**Test command**: `bundle exec rspec --format json`.
+
+**Edge case**: Rails projects may split specs across `spec/` and `spec/system/`. The default command covers both; no extra path is needed.
+
+### phpunit
+
+**Signal**: `composer.json` lists `phpunit/phpunit` in `require-dev`, or a `phpunit.xml` / `phpunit.xml.dist` file exists.
+
+**Test command**: `./vendor/bin/phpunit --log-junit /tmp/phpunit.xml` (the skill parses the JUnit XML).
+
+**Edge case**: Laravel projects use `php artisan test`, which wraps phpunit. Prefer the artisan command when `artisan` exists at the repo root.
+
+### bats
+
+**Signal**: `tests/` contains `*.bats` files and `bats-core` is available (`command -v bats`).
+
+**Test command**: `bats --tap tests/` (TAP output, parseable line-by-line).
+
+**Edge case**: BATS projects often use `tests/test_helper/bats-support/` and `bats-assert/`. No special handling is needed — the TAP output is framework-neutral.
+
+### other
+
+**Signal**: None of the above match, but `.cleo/project-context.json#testing.command` is populated.
+
+**Test command**: Run the command from `testing.command` verbatim. Parse stdout + stderr and the exit code. The skill MUST NOT guess at structure — success is exit 0 and nothing else.
+
+**Edge case**: If the command is a shell script that wraps multiple frameworks, the skill treats the wrapper as the framework and records `framework: other` in the manifest.
+
+## Detection Failures
+
+| Failure | Exit Code | Remediation |
+|---------|-----------|-------------|
+| No framework detected and no `testing.command` hint | 65 (HANDOFF_REQUIRED) | Add `.cleo/project-context.json#testing.framework` or `testing.command` |
+| Two conflicting signals (e.g., jest and vitest both present) | 65 | Use the project-context hint to disambiguate |
+| Framework detected but command not on PATH (`bats: command not found`) | 65 | Install the missing tool or update CI image |
+| Framework detected but tests directory is empty | 65 | Add at least one test before running the loop |
+
+Detection is diagnostic, not speculative. If the skill cannot pick exactly one framework, it exits 65 and lets the human reviewer decide.
+
+## Monorepos
+
+Monorepo detection follows the same table but is scoped per package. The skill reads the task's declared package (from the task metadata) and walks detection from that package's root, not the monorepo root. This prevents a `pyproject.toml` in one package from confusing the detector for a JS package next to it.

package/skills/ct-ivt-looper/references/loop-anatomy.md

@@ -0,0 +1,156 @@
+# Anatomy of One IVT Iteration
+
+This file walks through a single iteration of the IVT loop, from the failure diagnosis to the regenerated fix. Read it before modifying the loop logic.
+
+## Scenario
+
+Task T5142 requires a function `normalizeEmail(input: string): string` with the following spec:
+
+| MUST | Requirement |
+|------|-------------|
+| MUST-1 | Trim leading and trailing whitespace. |
+| MUST-2 | Lowercase the local part and the domain. |
+| MUST-3 | Reject empty strings by throwing `ValidationError`. |
+| MUST-4 | Reject strings with more than one `@` by throwing `ValidationError`. |
+
+The implementer has produced an initial patch. The loop enters iteration 1.
+
+## Iteration 1: Implement
+
+The patch adds the function skeleton:
+
+```ts
+export function normalizeEmail(input: string): string {
+  return input.trim().toLowerCase();
+}
+```
+
+Provenance tags are present (`@task T5142`). The Implement phase ends.
+
+## Iteration 1: Validate
+
+The lint phase passes. The type check passes. No errors yet. The Validate phase ends.
+
+## Iteration 1: Test
+
+The framework (vitest) is invoked:
+
+```
+$ pnpm vitest run --reporter=json
+PASS  tests/normalize-email.test.ts
+  normalizeEmail
+    ✓ trims whitespace
+    ✓ lowercases local and domain
+    ✗ throws on empty string
+    ✗ throws on double @
+```
+
+Raw result: `testsRun=4, testsPassed=2, testsFailed=2`.
+
+### Spec-to-test trace
+
+| Spec MUST | Test | Passing? |
+|-----------|------|----------|
+| MUST-1 | `trims whitespace` | yes |
+| MUST-2 | `lowercases local and domain` | yes |
+| MUST-3 | `throws on empty string` | **no** |
+| MUST-4 | `throws on double @` | **no** |
+
+Two failures, both tied to MUST requirements. Convergence = false. The Test phase ends.
+
+## Iteration 1: Diagnose
+
+The diagnose step reads each failure and maps it to a spec clause:
+
+| Failure | Spec Clause | Root cause |
+|---------|-------------|------------|
+| `throws on empty string` | MUST-3 | Implementation does not throw on empty input |
+| `throws on double @` | MUST-4 | Implementation does not validate `@` count |
+
+A fix is generated:
+
+```ts
+export function normalizeEmail(input: string): string {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw new ValidationError('email cannot be empty');
+  }
+  if ((trimmed.match(/@/g) ?? []).length !== 1) {
+    throw new ValidationError('email must contain exactly one @');
+  }
+  return trimmed.toLowerCase();
+}
+```
+
+The loop increments `iteration` to 2 and re-enters Implement.
+
+## Iteration 2: Implement, Validate, Test
+
+Patch applies cleanly. Lint and type check pass. Vitest runs:
+
+```
+PASS  tests/normalize-email.test.ts
+  normalizeEmail
+    ✓ trims whitespace
+    ✓ lowercases local and domain
+    ✓ throws on empty string
+    ✓ throws on double @
+
+Tests  4 passed (4)
+```
+
+Spec trace is complete. All four MUST requirements map to passing tests.
+
+## Convergence
+
+The loop writes:
+
+```json
+{
+  "agent_type": "testing",
+  "framework": "vitest",
+  "testsRun": 4,
+  "testsPassed": 4,
+  "testsFailed": 0,
+  "ivtLoopConverged": true,
+  "ivtLoopIterations": 2,
+  "key_findings": [
+    "4/4 tests pass",
+    "all 4 MUST requirements covered",
+    "converged in 2 iterations"
+  ]
+}
+```
+
+Exit code 0. The task advances to the next stage.
+
+## What This Iteration Teaches
+
+1. **The loop is spec-driven, not test-driven.** If iteration 1 had produced a fifth test that passes but does not map to any MUST, it would still not count toward convergence. Convergence is defined by spec coverage, not raw pass count.
+
+2. **Lint and type check run every iteration.** Even though they passed in iteration 1, they run again in iteration 2. Regressions are possible and must be caught inside the loop, not after it.
+
+3. **The diagnose step maps failures to spec clauses, not to tests.** This is how the loop avoids the anti-pattern of deleting assertions: you cannot satisfy a spec clause by removing the test that checks it, because the trace still shows the clause as uncovered.
+
+4. **Iterations end with a single atomic manifest write.** The manifest is not appended to during the loop — only at the end, once convergence is decided. This keeps the canon immutable and the loop deterministic.
+
+## Pathological Cases
+
+### Fake convergence via assertion deletion
+
+An untrained implementer might delete the failing assertion:
+
+```ts
+// was:  expect(() => normalizeEmail('')).toThrow();
+// now:  expect(() => normalizeEmail('')).not.toThrow();
+```
+
+Tests now pass. The spec trace, however, still lists MUST-3 as uncovered: the assertion no longer checks the MUST clause. Convergence fails and the loop continues until MAX_ITERATIONS, then escalates. Do not accept this pattern.
+
+### Coverage inflation
+
+An implementer adds 50 trivial tests to hit a coverage number. The spec trace still has gaps. Convergence fails. Coverage is advisory; the spec trace is authoritative.
+
+### Fix regression
+
+Iteration 2's fix breaks the test that iteration 1 made pass. Validate or Test catches this and the loop re-diagnoses. This is normal; the iteration cap exists precisely to bound it.

package/skills/ct-orchestrator/manifest-entry.json

@@ -2,7 +2,7 @@
   "name": "ct-orchestrator",
   "version": "4.0.0",
   "description": "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation.",
-  "path": "packages/ct-skills/skills/ct-orchestrator",
+  "path": "packages/skills/skills/ct-orchestrator",
   "status": "active",
   "tier": 0,
   "core": true,