Troubleshooting

Start with read-only evidence#

These recovery steps apply to the version-pinned RC.8 command surface.

Do not guess whether the workspace, Task, or remote is healthy. Begin with the narrow read that matches the symptom.

ait status --json
ait diff --stat
ait queue summary
ait worktree status --json

Keep the exact error and next-action text. AIT decision surfaces intentionally report the command that can safely advance or inspect the current state.

The repository is not initialized#

Run ait init from the intended repository root. If an .ait directory exists but is incomplete, do not replace it blindly; inspect the error and use the bounded repair option only when it matches the reported condition.

A regression needs attribution#

Use ait blame on the smallest useful source range before selecting a repair.

ait blame <path> --line <number>

Record the repair in a new sprint item and Task. Completed lineage remains historical evidence.

A Task workspace is missing or stale#

Inspect the Task and worktree before recreating materialization.

ait task audit <task-id>
ait worktree doctor --refresh --json

Follow the exact recovery command reported for that Task. Preserve unrelated workspace changes and avoid deleting a path that is not precisely identified as AIT-owned.

Remote readiness is pending#

Run the text-only readiness surface again and follow its stated gate.

ait workflow ready <change-id> --apply

Local test success does not substitute for required remote CI. A failed review, policy, attestation, or CI gate must remain visible until its owning evidence is corrected.

The server or runner is unavailable#

Check the configured remote, server health, repository index, runner compatibility, and repository-owned CI entrypoint. Do not switch a remote-backed Task to a different authority merely to bypass the failure.

Escalate without destroying evidence#

When recovery requires a new user decision, stop with the current Task, Snapshot, and worktree intact. Report the exact identifier, failing gate, command output, and last successful validation.