# Task 5 Report — `tht setup` lifecycle orchestration

## Status

Completed. `tht setup` now validates the checkout and host prerequisites, creates or validates
the non-secret installation files, validates Compose, and by default builds, starts, health-checks,
and verifies the installation. `tht setup --configure-only` stops immediately after successful
Compose rendering.

## Implementation

- Added `setup.Run`, with an ordered host preflight: project/worktree discovery, Docker Engine,
  Docker Compose, supported architecture, and LF line-ending checks.
- Reused `config.Installation.ComposeArgs` for all Compose calls and added a narrow
  `compose.InstallationRunner` adapter for Pi diagnostics; no shell command construction was added
  to the top-level CLI parser.
- Default setup performs `compose build`, `compose up --detach --remove-orphans`, bounded polling
  for `core`, `frontend`, `qdrant`, `embedding`, and `embedding-model-init`, then aggregate volume
  diagnostics and `pi.Doctor`.
- Health timeout errors identify the last failing service and preserve containers for diagnosis,
  with `tht logs <service>` and `tht status` guidance.
- Completion output includes the frontend URL, selected descriptor, and next action.

## TDD evidence

The initial focused test run failed because `setup.Run` did not exist. Tests were then written
against a fake Compose runner before the orchestration was implemented. They cover the complete
ordered flow, configure-only stop, preflight failure before writing configuration, health retry,
timeout guidance, and CLI default versus `--configure-only` dispatch.

## Verification

Executed from `tools/tht`:

```bash
go test ./internal/setup ./internal/compose ./cmd/tht -run 'TestRun|TestSetupCommand|TestInstallationRunner' -count=1
go test ./internal/setup ./internal/compose ./cmd/tht -count=1
go test ./...
git diff --check
```

All commands passed. No actual Docker build, container start, live-stack restart, system
installation, Pi configuration edit, or documentation rewrite was performed.

## Commit

`feat(setup): build start and verify ThothII` (this report is included in that commit).

## Concerns

- The bounded health wait is verified with fakes only, as required for this task. Real Docker
  lifecycle verification belongs to the later live acceptance task.
- The existing aggregate `tht doctor` command remains a separate implementation; Task 5 performs
  its equivalent setup-time prerequisite checks plus `pi.Doctor` without invoking a nested CLI
  process.

## Fix round 1

The independent review identified three gaps. All were reproduced with RED tests before the
production change:

- A rendered Compose document containing any one volume was accepted. `requireVolumes` now
  requires `settings`, `pi-state`, `workspace-registry`, `workspace-secrets`, `sessions`,
  `qdrant-data`, and `embedding-models`; tests reject each individual omission and an
  unrelated-only volume set.
- Failures after `compose up` could return without recovery instructions. A single recovery
  wrapper now preserves the underlying error while adding the retained-container, `tht logs
  <service>`, and `tht status` guidance for failed `up`, health, aggregate doctor, and Pi doctor
  phases. Focused tests also prove build failure stops before attempting startup.
- LF inspection previously walked the full checkout. It now inspects only `compose.yaml`,
  `deploy/`, and `docker/`; a test proves CRLF content under `node_modules/` is ignored.

Verification added for this round:

```bash
go test ./internal/setup -run 'TestRequireVolumes|TestRun(BuildFailure|UpFailure|AggregateDoctorFailure|PiDoctorFailure|IgnoresIrrelevant|TimesOut)' -count=1
go test ./internal/setup -count=1
```

Both passed before the final full-suite verification. No Docker or live operation was run.

Implementation commit evidence: `ea70cc95b04532043744a9de6c5912e30a214595` —
`fix(setup): harden verification and recovery`.