Loop Execution

1. Is this a git repo with at least one commit?
   - No  → log "Skipping branch setup (no git history)" → proceed to step execution
   - Yes → continue

2. Check for uncommitted changes
   - First, exclude HOTL-owned transient artifacts from the dirty check:
     • docs/plans/*-workflow.md (canonical workflow files)
     • hotl-workflow-*.md (legacy workflow files)
     • docs/designs/*.md (canonical design docs from brainstorming)
     • docs/plans/*-design.md, docs/plans/*-plan.md (legacy design docs from brainstorming)
     • .hotl/ (runtime state, reports, cache)
   - If only HOTL artifacts are dirty → treat as clean, continue
   - If non-HOTL dirty files exist:
     • If dirty_worktree: allow in workflow frontmatter → proceed without prompting
     • Otherwise → HARD-FAIL. Tell the user which non-HOTL files are dirty. Offer choices:
       a. Clean up manually, then re-run
       b. Stash manually, then re-run
       c. Explicitly approve HOTL to stash and continue
   - Clean → continue

3. Determine branch name
   - If branch: field exists in workflow frontmatter → use it
   - Otherwise → derive `hotl/<slug>` from the workflow filename
     • Canonical: strip `YYYY-MM-DD-` prefix and `-workflow.md` suffix from `docs/plans/YYYY-MM-DD-<slug>-workflow.md`
     • Legacy: strip `hotl-workflow-` prefix and `.md` suffix from `hotl-workflow-<slug>.md`

4. Capture authoring origin
   - Record the current branch name (if any) and current `HEAD` commit as the workflow's authoring origin
   - If the current branch is neither `main` nor `master`, and the workflow frontmatter does not already set `branch:` or `worktree:`, PAUSE and ask:
     a. Continue on the current branch in this checkout
        → set `branch: <current-branch>` and `worktree: false`
     b. Use HOTL's isolated execution branch/worktree (recommended)
        → leave `worktree: true` and let HOTL derive `hotl/<slug>` unless the user wants a custom branch name
     c. Use a custom execution branch
        → set `branch: <user-branch>` and keep worktree isolation unless the user explicitly opts out
   - Explain clearly: the authoring checkout and the execution checkout can differ. HOTL can execute in a separate worktree while leaving the current checkout untouched

5. Determine isolation mode
   - If `worktree: host` in frontmatter → stay on the current checkout's current feature branch exactly as provided by the host tool; reject `main` and `master`
   - If `worktree: false` in frontmatter → stay in the current checkout and use a dedicated branch there
   - If the current checkout is already a named linked git worktree, and the workflow frontmatter does not set `branch:` or `worktree:`, use host mode automatically to avoid stacking another worktree
   - Otherwise → use an isolated git worktree by default

6. Check if the target branch/worktree already exists locally
   - Current helper behavior: existing branch/worktree collisions are a hard stop, not an interactive reuse/recreate flow
   - If the helper reports an existing branch/worktree conflict, stop and ask the user whether to reuse manually, delete+recreate manually, or abort
   - Does not exist → create (no prompt)

7. Resolve the execution root with `scripts/hotl-prepare-execution-root.sh <workflow-file> --executor-mode <mode>`
   - The helper returns JSON with: `branch`, `repo_root`, `execution_root`, `workflow_path`, `source_workflow_path`, `source_branch`, `source_head`, `worktree_path`
   - By default it creates a linked git worktree for the branch, copies the current workflow into that worktree, and returns that worktree as `execution_root`
   - If `worktree: false` in frontmatter → create/switch to the dedicated branch in the current checkout and return the repo root as `execution_root`
   - If `worktree: host` in frontmatter → keep the current branch and return the current checkout as `execution_root`; if `branch:` is set, it must match the current branch
   - If `branch:` matches the currently checked-out branch while worktree isolation is still enabled, the helper must STOP with a clear message telling the user to set `worktree: false` or `worktree: host` for same-branch continuity
8. Change into `execution_root`
   - Every later git command, runtime call, Codex helper call, and review command for this run MUST execute from that directory

1. Resolve workflow file (see above)
2. Parse frontmatter: intent, risk_level, auto_approve, branch, worktree
3. Run Branch/Worktree Preflight (see above)
4. Capture preflight metadata and change into `execution_root`
5. Initialize and claim the run via runtime:
   - Run: `hotl-rt init <workflow-file> --require-owner --executor-mode loop --repo-root <repo-root> --execution-root <execution-root> --source-workflow-path <source-workflow-path> --source-branch <source-branch|null> --source-head <source-head|null> --worktree-path <worktree-path|null> --branch <branch>`
   - This parses the workflow, creates .hotl/state/<run-id>.json with all steps, and initializes .hotl/reports/<run-id>.md
   - Capture the run_id from stdout
   - Immediately run `hotl-rt owner claim --owner <stable-controller-id> --lease-seconds <bounded-lease> --run-id <run-id>`. Parse the one-time `token` from its JSON response, retain it only in the controller, export it as `HOTL_OWNER_TOKEN`, and clear any temporary response variable. Never write the raw token to chat, reports, prompts, or committed files.
   - Run `hotl-rt owner heartbeat --lease-seconds <bounded-lease> --run-id <run-id>` before and after long actions and at safe transition boundaries. Use explicit `owner handoff`, `owner release`, or reviewed `owner takeover`; timestamp age alone never grants ownership.
   - For every later mutating `hotl-rt step`, `hotl-rt gate`, `hotl-rt action`, `hotl-rt budget`, `hotl-rt finalize`, `hotl-rt finish`, and owner call, keep `HOTL_OWNER_TOKEN` in the controller environment. Pass `--run-id <run-id>` or set `HOTL_RUN_ID=<run-id>` for all runtime and helper calls.
   - Never let the runtime silently choose "the newest run" when multiple runs exist
   - Only after init and `owner claim` succeed should chat output or native plan/progress UI show anything

6. For each step in order:

   a. Start step via runtime:
      - Run: `hotl-rt step N start --run-id <run-id>`
      - This persists step start (status, timestamp, attempts) to state and report
      - Only after the runtime call succeeds should chat show "→ Step N"

   b. Announce: "→ Step N: [name]"

   c. Execute the action (agent implements the work)
      - Heartbeat immediately before starting and after returning from any action that may run for a meaningful fraction of the lease.
      - Host goals, automations, background sessions, handoffs, and hooks are scheduling and liveness only. The controller must still persist every transition through HOTL. Preview and experimental host continuation features are opt-in.
      - For `external_write`, `production_change`, or `secret_access`, first run `hotl-rt action request <kind> --target <bounded-target> --idempotency-key <stable-key> --run-id <run-id>`, obtain the required human decision with `action decide`, then persist intent with `action begin <action-id> --idempotency-key <stable-key> --run-id <run-id>` before performing the effect.
      - After observing the effect, run `action complete <action-id> <succeeded|failed|cancelled> --evidence-ref <reference> --run-id <run-id>`. If execution was interrupted or the outcome is uncertain, inspect the target and use `action reconcile`; never replay an `in_progress` or `uncertain` effect blindly.

   d. Verify via runtime:
      - Run: `hotl-rt step N verify --run-id <run-id>`
      - The runtime runs the verify command, captures stdout/stderr, and atomically transitions the step to done or failed
      - If the verify type is unsupported, the runtime blocks the step with a clear reason
      - For type: browser — `hotl-rt` downgrades to a paused human-review request when browser tooling is unavailable inside the runtime. If the controller has platform browser tooling, perform the browser check before approving or rejecting that pause.
      - For type: human-review — the runtime returns a `human review required: ...` block reason and sets the run status to `paused`; ALWAYS pause for human (never auto-approve)
      - For type: artifact — runtime checks path exists and evaluates assert; for `matches-glob`, `path` must be the directory and `value` must be a filename glob only, so `src/*` is invalid and should be authored as `path: src`
      - Runtime transitions enforce step order, per-step `max_iterations`, aggregate attempt and elapsed-time limits, and configured budget pauses. Run `hotl-rt budget check --run-id <run-id>` when external agent or cost telemetry was recorded or before launching another costly/long action.

   e. If verify fails (runtime returns non-zero):

      e0. If the runtime output says `blocked: human review required: ...`
         → PAUSE immediately. Do not start later steps or finalize the run.
         → Show the review prompt to the human and ask: "Continue? (yes/no/show-details)"
         → If the human says yes/approve/continue:
             Run: `hotl-rt gate N approved --mode human --run-id <run-id>`
             Then continue to the next step
         → If the human says no/reject:
             Run: `hotl-rt gate N rejected --mode human --run-id <run-id>`
             STOP and surface the report path
         → If the human asks for details:
             Show the relevant test/report context, then wait again
         → Never treat the chat reply alone as persisted approval; the approval is only real after the `hotl-rt gate ...` call succeeds

      f. If loop: false
         → STOP, report to human
         → Run: `hotl-rt step N block --reason "verify failed" --run-id <run-id>` if not already marked failed by verify
         → Show last verify output. Wait for human guidance.

      g. If loop: until [condition]
         → if iterations < max_iterations:
             Run: `hotl-rt step N retry --run-id <run-id>` then `hotl-rt step N start --run-id <run-id>`
             log "↻ Retrying ([n]/[max])...", retry the action
         → if iterations = max_iterations: STOP
             Report: "Step N reached max iterations ([max]). [condition] not met."
             Show last verify output. Wait for human guidance.

      h. On step completion (verify passed):
      - The runtime has already persisted the done status
      - Update the workflow checkbox to [x]
      - Only after the runtime confirms success should chat show "✓ Step N"

   i. If gate: human
      → if auto_approve: true AND risk_level != high:
          Run: `hotl-rt gate N approved --mode auto --run-id <run-id>`
          log "⚡ Auto-approved: Step N gate (risk: [risk_level])"
          continue
      → else:
          PAUSE. Show summary of what was done in this step.
          Ask: "Gate reached at Step N. Continue? (yes/no/show-details)"
          Wait for human response.
          Run: `hotl-rt gate N approved --mode human --run-id <run-id>` or `hotl-rt gate N rejected --mode human --run-id <run-id>`

   j. If gate: auto
      → Run: `hotl-rt gate N approved --mode auto --run-id <run-id>`
      → always continue, log "⚡ Auto-approved: Step N gate"

7. All steps complete:
   → Run review checkpoint (see Review Checkpoints below)
   → Invoke hotl:verification-before-completion skill
   → For Codex final summaries, run: `scripts/finalize-codex-summary.sh <run-id>` (or set `HOTL_RUN_ID`)
   → For Claude Code/Cline, run: `hotl-rt finalize --json --run-id <run-id>`, write the payload to a temp file, then render it with: `scripts/render-execution-summary.sh --platform <claude|cline> <summary-json-file>`
   → Successful finalize sets status to `ready_to_finish`, not `completed`. It proves step/gate/effect/budget readiness but does not invent a branch disposition.
   → Do not freehand the final summary when the renderer is available
   → Invoke `hotl:finishing-a-development-branch` with the same `run_id` and retain `HOTL_OWNER_TOKEN`. Even non-git runs require an explicit `kept` disposition before completion.
   → Never silently merge, publish, keep, or discard the execution branch/worktree
   → After `hotl-rt finish` moves a successful run from `ready_to_finish` to `completed`, run `owner release`, then require `hotl-rt receipt <run-id> --json` to report `sufficiency.sufficient: true`.
   → Only then show the rendered summary as visible chat output in the final response; do not paraphrase it away or claim completion earlier.