unit-test-deep

# Unit-Test Coverage Improvement (Deep)

Orchestrate paired cycles of test generation and testability refactoring. Each cycle is two subagent dispatches: first `/optimus:unit-test` (writes tests, measures coverage, flags untestable code), then `/optimus:refactor` with focus on testability (unblocks the flagged items so the next cycle can cover them). All state lives in `.claude/unit-test-deep-progress.json`.

## Step 1: Parse Arguments and Guard Against Re-entry

### Re-entry guard

If your invocation prompt body already contains `HARNESS_MODE_INLINE`, stop immediately with: *"Deep mode cannot run inside deep mode."*

### Parse invocation arguments

Extract from the user's arguments:
1. `--resume` flag (present/absent)
2. `--no-commit` flag (present/absent)
3. `--yes` flag (present/absent) — auto-confirm the Step 3 prompt; required when invoked under `claude -p` or any other non-interactive session that cannot answer `AskUserQuestion`.
4. `--max-cycles N` (optional, default 5, hard cap 10)
5. Everything else → scope text (optional path filter)

Examples:
- `/optimus:unit-test-deep` → 5 cycles, full project
- `/optimus:unit-test-deep --max-cycles 8` → 8 cycles
- `/optimus:unit-test-deep src/api` → scoped
- `/optimus:unit-test-deep --resume` → continue from existing progress file
- `/optimus:unit-test-deep --no-commit` → skip per-phase checkpoint commits
- `claude -p "/optimus:unit-test-deep --yes src/api"` → headless / CI usage; skips the Step 3 confirmation prompt

## Step 2: Pre-flight Checks

### Plugin root

Resolve `plugin_root` (the absolute path to the installed plugin) and keep it for every CLI call and subagent dispatch below — the env var does not persist across separate Bash tool calls and reads empty on some platforms (notably Windows):

1. Run `echo $CLAUDE_PLUGIN_ROOT` via Bash. If it is non-empty **and** `<value>/scripts/harness_common` exists (`test -d`), use it.
2. Otherwise derive the root from the "Base directory for this skill:" line in your invocation context — strip the trailing `/skills/...` segment (this skill's own directory) — and use it if `<derived>/scripts/harness_common` exists.
3. If neither candidate contains `scripts/harness_common`, stop: *"Cannot resolve plugin root — ensure optimus-claude is installed via the Claude Code plugin system."*

Wherever the steps below (and `orchestrator-loop-*.md`) write `$CLAUDE_PLUGIN_ROOT`, use this resolved `plugin_root`; if `echo $CLAUDE_PLUGIN_ROOT` was empty, substitute the absolute path literally.

### Documentation prerequisites

Read `$CLAUDE_PLUGIN_ROOT/skills/init/references/prerequisite-check.md` and apply the prerequisite check. If `.claude/CLAUDE.md` is missing, stop: *"Deep mode requires `/optimus:init` to set up project context first."*

### Test command

Read `.claude/CLAUDE.md` and capture the documented test command verbatim — store the exact string (e.g. `npm test`, `pytest`) as `test_command`. If none is documented, stop and recommend `/optimus:init` to set one up first (the auto-fix loop has no safety net without a test command). You pass this captured command to `init` in Step 4 via `--test-command`; `init` can also parse `.claude/CLAUDE.md` itself, but its parser is stricter than a human read, so passing the command you just read avoids a spurious "No test command found" failure on a command the CLI can't parse.

### Test infrastructure

The base `/optimus:unit-test` skill requires a test framework to be installed. If `/optimus:init` flagged the test framework as missing or "installed but no tests yet," warn the user but proceed — the unit-test phase will surface the gap.

### Git state

On a fresh (non-`--resume`) run, refuse to proceed if the working tree has uncommitted changes unless `--no-commit` is passed.

## Step 3: User Confirmation

Skip this step entirely when `--resume` is given, or when `--yes` is given (headless / CI: the caller has pre-approved the run).

Warn the user with:

> **Deep unit-test mode** runs up to [N] cycles. Each cycle is two subagent dispatches: a unit-test phase that writes tests + measures coverage, and a refactor phase (only when the first phase flags untestable code) that unblocks testability barriers. Credit and time consumption multiplies with cycle count. Tests and refactor fixes are applied automatically without per-change approval. Press Esc twice to interrupt — state is saved per-phase; resume with `/optimus:unit-test-deep --resume`.
>
> Test command: `[test command]`

Use `AskUserQuestion` — header "Deep unit-test", question "Proceed with deep unit-test?":
- **Proceed** — "Run the unit-test + refactor cycle loop (max [N] cycles)"
- **Cancel** — "Don't run deep mode"

If the user selects **Cancel**, stop.

## Step 4: Initialize or Resume Progress

### On `--resume`

```bash
PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli resume \
    --progress-file ".claude/unit-test-deep-progress.json" \
    [--max-cycles N] \
    --project-dir "."
```

Pass `--max-cycles N` through when the user supplied a higher cap on `--resume` — `resume` raises the persisted cycle cap (and clears a prior `diminishing-returns` stop) so the loop continues past the previous limit. A run that finished cleanly is archived to `.done.json`; `--resume` only continues a still-on-disk run (interrupt or `diminishing-returns`).

### On fresh run

```bash
PYTHONPATH="$CLAUDE_PLUGIN_ROOT/scripts" python -m harness_common.cli init \
    --skill unit-test \
    --max-cycles [N] \
    --test-command "<test_command>" \
    [--scope "<scope>"] \
    [--no-commit] \
    --progress-file ".claude/unit-test-deep-progress.json" \
    --project-dir "."
```

Pass `--no-commit` through to `init` when the user supplied it — the mode is persisted in the progress file, so `--resume` keeps it without re-passing the flag (and `commit-checkpoint` self-skips regardless).

If `init` reports *"progress file already exists"*, a prior un-archived run is on disk. Either run with `--resume` to continue