[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6MP8RTHK46DJCH46STBNVQ4":3,"skill-same:01M6MP8RTHK46DJCH46STBNVQ4":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":34,"linkOnly":35,"markdownContent":36,"markdownBody":37,"frontMatter":38,"refName":39,"commitSha":40,"skillDirectory":41,"forksCount":42,"repositoryHtmlUrl":43,"repositoryHomepageUrl":44,"ownerHtmlUrl":45,"ownerBlogUrl":46,"ownerDescription":47,"updatedAt":48,"install":49,"resources":62},"01M6MP8RTHK46DJCH46STBNVQ4","loop-execution",null,"Use when executing an existing HOTL workflow file — reads steps, loops until success criteria met, auto-approves low-risk gates, pauses at high-risk gates.","hashgraph-online\u002Fawesome-codex-plugins","hashgraph-online","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F160371962?v=4","01M6CNB6NRJVNNGN14TR01Q6D3","HOL (Hashgraph Online)","01M6JT1HSKKG9V68KQAQGBA7XP",1575,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fyimwoo\u002Fhotl-plugin\u002Fskills\u002Floop-execution\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33],"execution","loop","loop execution","workflow","file","risk","use","auto","gates","loops","high","at","Existing","hotl","when","2026-11-10 10:12:30",false,"---\nname: loop-execution\ndescription: Use when executing an existing HOTL workflow file — reads steps, loops until success criteria met, auto-approves low-risk gates, pauses at high-risk gates.\n---\n\n# HOTL Loop Execution\n\n## Overview\n\nExecute an existing HOTL workflow file autonomously. Canonical workflows live at `docs\u002Fplans\u002FYYYY-MM-DD-\u003Cslug>-workflow.md`, with legacy root `hotl-workflow-\u003Cslug>.md` still accepted during migration. Loop on steps with success criteria. Auto-approve low-risk gates. Always pause for high-risk gates.\n\n`governed-execution` is the preferred new router for host-native or fallback runs. This skill remains the canonical autonomous state machine and a supported explicit compatibility profile. When invoked through the router, use the selected driver for lifecycle calls and require a sufficient evidence receipt before completion.\n\n**Announce:** \"Starting HOTL loop execution. Looking for workflow file...\"\n\n## Workflow File Resolution\n\nResolve which workflow file to execute:\n\n1. If the user specified a filename → use that file\n2. Else, glob for canonical workflows in `docs\u002Fplans\u002F*-workflow.md`:\n   - **One match** → use it automatically\n   - **Multiple matches** → if one is clearly the newest revision for the same semantic slug, prefer it; otherwise list them and ask the user to pick\n3. If no canonical matches, glob for legacy `hotl-workflow*.md` in project root:\n   - **One match** → use it automatically\n   - **Multiple matches** → list them and ask the user to pick\n4. **No matches** → see \"What to Do If No Workflow Found\" below\n\n### Interrupted Run Detection\n\nAfter resolving the workflow file, locate interrupted runs **before** Branch\u002FWorktree Preflight. Use `scripts\u002Fhotl-locate-run.sh --workflow \u003Cworkflow-file>` when available. This helper scans the current checkout, linked git worktrees, and HOTL's default `.hotl-worktrees\u002F\u003Crepo>\u002F` directory, so it can find state created inside an isolated execution worktree even when the new session starts from the authoring checkout.\n\nIf the helper is unavailable, manually scan these locations for `.hotl\u002Fstate\u002F*.json` and match `workflow_path` or `source_workflow_path` against the resolved workflow:\n1. Current checkout\n2. `git worktree list --porcelain` roots for the repo\n3. `$(dirname \u003Crepo-root>)\u002F.hotl-worktrees\u002F$(basename \u003Crepo-root>)\u002F*`\n\n- **One interrupted run found** → ask: \"Found an interrupted run (step N\u002FM). Resume from step N, or start fresh?\"\n- **Multiple interrupted runs found** → list all with run_id, step progress, branch, age. Ask which to resume or start fresh. **Never silently choose.**\n- **No interrupted runs** → proceed normally (new run)\n\nIf the user chooses resume, do not run Branch\u002FWorktree Preflight again. Load the matched sidecar, change into its recorded `execution_root`, and follow `skills\u002Fresuming\u002FSKILL.md` with the original `run_id`.\n\n## Branch\u002FWorktree Preflight\n\nAfter resolving the workflow file, run this preflight **before executing any steps**:\n\n```\n1. Is this a git repo with at least one commit?\n   - No  → log \"Skipping branch setup (no git history)\" → proceed to step execution\n   - Yes → continue\n\n2. Check for uncommitted changes\n   - First, exclude HOTL-owned transient artifacts from the dirty check:\n     • docs\u002Fplans\u002F*-workflow.md (canonical workflow files)\n     • hotl-workflow-*.md (legacy workflow files)\n     • docs\u002Fdesigns\u002F*.md (canonical design docs from brainstorming)\n     • docs\u002Fplans\u002F*-design.md, docs\u002Fplans\u002F*-plan.md (legacy design docs from brainstorming)\n     • .hotl\u002F (runtime state, reports, cache)\n   - If only HOTL artifacts are dirty → treat as clean, continue\n   - If non-HOTL dirty files exist:\n     • If dirty_worktree: allow in workflow frontmatter → proceed without prompting\n     • Otherwise → HARD-FAIL. Tell the user which non-HOTL files are dirty. Offer choices:\n       a. Clean up manually, then re-run\n       b. Stash manually, then re-run\n       c. Explicitly approve HOTL to stash and continue\n   - Clean → continue\n\n3. Determine branch name\n   - If branch: field exists in workflow frontmatter → use it\n   - Otherwise → derive `hotl\u002F\u003Cslug>` from the workflow filename\n     • Canonical: strip `YYYY-MM-DD-` prefix and `-workflow.md` suffix from `docs\u002Fplans\u002FYYYY-MM-DD-\u003Cslug>-workflow.md`\n     • Legacy: strip `hotl-workflow-` prefix and `.md` suffix from `hotl-workflow-\u003Cslug>.md`\n\n4. Capture authoring origin\n   - Record the current branch name (if any) and current `HEAD` commit as the workflow's authoring origin\n   - If the current branch is neither `main` nor `master`, and the workflow frontmatter does not already set `branch:` or `worktree:`, PAUSE and ask:\n     a. Continue on the current branch in this checkout\n        → set `branch: \u003Ccurrent-branch>` and `worktree: false`\n     b. Use HOTL's isolated execution branch\u002Fworktree (recommended)\n        → leave `worktree: true` and let HOTL derive `hotl\u002F\u003Cslug>` unless the user wants a custom branch name\n     c. Use a custom execution branch\n        → set `branch: \u003Cuser-branch>` and keep worktree isolation unless the user explicitly opts out\n   - Explain clearly: the authoring checkout and the execution checkout can differ. HOTL can execute in a separate worktree while leaving the current checkout untouched\n\n5. Determine isolation mode\n   - 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`\n   - If `worktree: false` in frontmatter → stay in the current checkout and use a dedicated branch there\n   - 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\n   - Otherwise → use an isolated git worktree by default\n\n6. Check if the target branch\u002Fworktree already exists locally\n   - Current helper behavior: existing branch\u002Fworktree collisions are a hard stop, not an interactive reuse\u002Frecreate flow\n   - If the helper reports an existing branch\u002Fworktree conflict, stop and ask the user whether to reuse manually, delete+recreate manually, or abort\n   - Does not exist → create (no prompt)\n\n7. Resolve the execution root with `scripts\u002Fhotl-prepare-execution-root.sh \u003Cworkflow-file> --executor-mode \u003Cmode>`\n   - The helper returns JSON with: `branch`, `repo_root`, `execution_root`, `workflow_path`, `source_workflow_path`, `source_branch`, `source_head`, `worktree_path`\n   - 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`\n   - If `worktree: false` in frontmatter → create\u002Fswitch to the dedicated branch in the current checkout and return the repo root as `execution_root`\n   - 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\n   - 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\n8. Change into `execution_root`\n   - Every later git command, runtime call, Codex helper call, and review command for this run MUST execute from that directory\n```\n\n**Rules:**\n- No auto-stash. Hidden state mutation weakens governance.\n- Existing branch\u002Fworktree collisions do not currently auto-prompt; treat them as a stop-and-ask condition until interactive reuse\u002Frecreate is implemented.\n- Non-git repos skip entirely — HOTL works without git ceremony.\n- Run HOTL structural lint (`scripts\u002Fdocument-lint.sh`) automatically on the workflow file before any git mutation or step execution. If lint fails, STOP and show all errors. If lint passes, continue silently.\n\n## HOTL Execution State Machine\n\nThis is the canonical HOTL execution state machine. Other execution modes (e.g., subagent-execution) reference this spec and define only their differences.\n\n```\n1. Resolve workflow file (see above)\n2. Parse frontmatter: intent, risk_level, auto_approve, branch, worktree\n3. Run Branch\u002FWorktree Preflight (see above)\n4. Capture preflight metadata and change into `execution_root`\n5. Initialize and claim the run via runtime:\n   - Run: `hotl-rt init \u003Cworkflow-file> --require-owner --executor-mode loop --repo-root \u003Crepo-root> --execution-root \u003Cexecution-root> --source-workflow-path \u003Csource-workflow-path> --source-branch \u003Csource-branch|null> --source-head \u003Csource-head|null> --worktree-path \u003Cworktree-path|null> --branch \u003Cbranch>`\n   - This parses the workflow, creates .hotl\u002Fstate\u002F\u003Crun-id>.json with all steps, and initializes .hotl\u002Freports\u002F\u003Crun-id>.md\n   - Capture the run_id from stdout\n   - Immediately run `hotl-rt owner claim --owner \u003Cstable-controller-id> --lease-seconds \u003Cbounded-lease> --run-id \u003Crun-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.\n   - Run `hotl-rt owner heartbeat --lease-seconds \u003Cbounded-lease> --run-id \u003Crun-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.\n   - 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 \u003Crun-id>` or set `HOTL_RUN_ID=\u003Crun-id>` for all runtime and helper calls.\n   - Never let the runtime silently choose \"the newest run\" when multiple runs exist\n   - Only after init and `owner claim` succeed should chat output or native plan\u002Fprogress UI show anything\n\n6. For each step in order:\n\n   a. Start step via runtime:\n      - Run: `hotl-rt step N start --run-id \u003Crun-id>`\n      - This persists step start (status, timestamp, attempts) to state and report\n      - Only after the runtime call succeeds should chat show \"→ Step N\"\n\n   b. Announce: \"→ Step N: [name]\"\n\n   c. Execute the action (agent implements the work)\n      - Heartbeat immediately before starting and after returning from any action that may run for a meaningful fraction of the lease.\n      - 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.\n      - For `external_write`, `production_change`, or `secret_access`, first run `hotl-rt action request \u003Ckind> --target \u003Cbounded-target> --idempotency-key \u003Cstable-key> --run-id \u003Crun-id>`, obtain the required human decision with `action decide`, then persist intent with `action begin \u003Caction-id> --idempotency-key \u003Cstable-key> --run-id \u003Crun-id>` before performing the effect.\n      - After observing the effect, run `action complete \u003Caction-id> \u003Csucceeded|failed|cancelled> --evidence-ref \u003Creference> --run-id \u003Crun-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.\n\n   d. Verify via runtime:\n      - Run: `hotl-rt step N verify --run-id \u003Crun-id>`\n      - The runtime runs the verify command, captures stdout\u002Fstderr, and atomically transitions the step to done or failed\n      - If the verify type is unsupported, the runtime blocks the step with a clear reason\n      - 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.\n      - 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)\n      - 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\u002F*` is invalid and should be authored as `path: src`\n      - 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 \u003Crun-id>` when external agent or cost telemetry was recorded or before launching another costly\u002Flong action.\n\n   e. If verify fails (runtime returns non-zero):\n\n      e0. If the runtime output says `blocked: human review required: ...`\n         → PAUSE immediately. Do not start later steps or finalize the run.\n         → Show the review prompt to the human and ask: \"Continue? (yes\u002Fno\u002Fshow-details)\"\n         → If the human says yes\u002Fapprove\u002Fcontinue:\n             Run: `hotl-rt gate N approved --mode human --run-id \u003Crun-id>`\n             Then continue to the next step\n         → If the human says no\u002Freject:\n             Run: `hotl-rt gate N rejected --mode human --run-id \u003Crun-id>`\n             STOP and surface the report path\n         → If the human asks for details:\n             Show the relevant test\u002Freport context, then wait again\n         → Never treat the chat reply alone as persisted approval; the approval is only real after the `hotl-rt gate ...` call succeeds\n\n      f. If loop: false\n         → STOP, report to human\n         → Run: `hotl-rt step N block --reason \"verify failed\" --run-id \u003Crun-id>` if not already marked failed by verify\n         → Show last verify output. Wait for human guidance.\n\n      g. If loop: until [condition]\n         → if iterations \u003C max_iterations:\n             Run: `hotl-rt step N retry --run-id \u003Crun-id>` then `hotl-rt step N start --run-id \u003Crun-id>`\n             log \"↻ Retrying ([n]\u002F[max])...\", retry the action\n         → if iterations = max_iterations: STOP\n             Report: \"Step N reached max iterations ([max]). [condition] not met.\"\n             Show last verify output. Wait for human guidance.\n\n      h. On step completion (verify passed):\n      - The runtime has already persisted the done status\n      - Update the workflow checkbox to [x]\n      - Only after the runtime confirms success should chat show \"✓ Step N\"\n\n   i. If gate: human\n      → if auto_approve: true AND risk_level != high:\n          Run: `hotl-rt gate N approved --mode auto --run-id \u003Crun-id>`\n          log \"⚡ Auto-approved: Step N gate (risk: [risk_level])\"\n          continue\n      → else:\n          PAUSE. Show summary of what was done in this step.\n          Ask: \"Gate reached at Step N. Continue? (yes\u002Fno\u002Fshow-details)\"\n          Wait for human response.\n          Run: `hotl-rt gate N approved --mode human --run-id \u003Crun-id>` or `hotl-rt gate N rejected --mode human --run-id \u003Crun-id>`\n\n   j. If gate: auto\n      → Run: `hotl-rt gate N approved --mode auto --run-id \u003Crun-id>`\n      → always continue, log \"⚡ Auto-approved: Step N gate\"\n\n7. All steps complete:\n   → Run review checkpoint (see Review Checkpoints below)\n   → Invoke hotl:verification-before-completion skill\n   → For Codex final summaries, run: `scripts\u002Ffinalize-codex-summary.sh \u003Crun-id>` (or set `HOTL_RUN_ID`)\n   → For Claude Code\u002FCline, run: `hotl-rt finalize --json --run-id \u003Crun-id>`, write the payload to a temp file, then render it with: `scripts\u002Frender-execution-summary.sh --platform \u003Cclaude|cline> \u003Csummary-json-file>`\n   → Successful finalize sets status to `ready_to_finish`, not `completed`. It proves step\u002Fgate\u002Feffect\u002Fbudget readiness but does not invent a branch disposition.\n   → Do not freehand the final summary when the renderer is available\n   → 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.\n   → Never silently merge, publish, keep, or discard the execution branch\u002Fworktree\n   → After `hotl-rt finish` moves a successful run from `ready_to_finish` to `completed`, run `owner release`, then require `hotl-rt receipt \u003Crun-id> --json` to report `sufficiency.sufficient: true`.\n   → Only then show the rendered summary as visible chat output in the final response; do not paraphrase it away or claim completion earlier.\n```\n\n## Execution State Persistence\n\nAll state persistence is handled by the `hotl-rt` shared runtime (`runtime\u002Fhotl-rt`). Agents do not manage state files directly.\n\nThe runtime owns:\n- `.hotl\u002Fstate\u002F\u003Crun-id>.json` — authoritative machine state (created by `hotl-rt init`, updated by owner\u002Fstep\u002Fgate\u002Faction\u002Fbudget\u002Ffinalize\u002Ffinish transitions)\n- `.hotl\u002Freports\u002F\u003Crun-id>.md` — durable Markdown report (initialized at init, updated incrementally, finalized at finalize)\n\nThe sidecar also records the execution location for the run: `repo_root`, `execution_root`, `workflow_path`, `source_workflow_path`, `worktree_path`, and `executor_mode`.\n\nRun ID format: `\u003Cslug>-\u003CYYYYMMDDTHHMMSSZ>-\u003C12-hex-nonce>` (e.g., `add-auth-20260320T212315Z-a1b2c3d4e5f6`). The entropy suffix prevents collisions across independent execution roots; legacy timestamp-only IDs remain readable.\n\nWorkflow checkboxes (`- [x]`) are a human-visible mirror updated by the agent on step completion. The sidecar is the source of truth.\n\nOperational rule: `hotl-rt` calls happen before the corresponding chat log or Codex native plan\u002Fprogress update. Native progress UI is never a substitute for the runtime-managed artifacts.\n\nConcurrency rule: after `hotl-rt init` returns a run id, claim the renewable controller and pin every later runtime\u002Fhelper call to that run id with `HOTL_OWNER_TOKEN`. Do not rely on \"latest file in .hotl\u002Fstate\" when more than one run exists, and do not use file age as takeover authority.\n\nSee `skills\u002Fresuming\u002FSKILL.md` for the full sidecar schema, stale run detection, and verify-first resume flow.\n\n### Path Resolution\n\nTo find `hotl-rt` and HOTL scripts (`document-lint.sh`, `hotl-locate-run.sh`, `render-execution-summary.sh`, etc.), resolve in this order:\n\n1. **Session context (Claude Code):** the session-start hook injects the plugin base path — use it to construct full paths like `bash \u003Cplugin-path>\u002Fruntime\u002Fhotl-rt init \u003Cworkflow-file>`\n2. **Codex native-skills install:** resolve from `~\u002F.codex\u002Fhotl\u002Fruntime\u002Fhotl-rt` and `~\u002F.codex\u002Fhotl\u002Fscripts\u002F`\n3. **Codex plugin install:** resolve from `~\u002F.codex\u002Fplugins\u002Fhotl-source\u002Fruntime\u002Fhotl-rt` and `~\u002F.codex\u002Fplugins\u002Fhotl-source\u002Fscripts\u002F`\n4. **Codex plugin cache fallback:** resolve from `~\u002F.codex\u002Fplugins\u002Fcache\u002Fcodex-plugins\u002Fhotl\u002F*\u002Fruntime\u002Fhotl-rt` and `~\u002F.codex\u002Fplugins\u002Fcache\u002Fcodex-plugins\u002Fhotl\u002F*\u002Fscripts\u002F`\n5. **Cline:** resolve from `~\u002FDocuments\u002FCline\u002FScripts\u002Fhotl-rt` and `~\u002FDocuments\u002FCline\u002FScripts\u002F`\n6. **Working in the hotl-plugin repo itself:** use `.\u002Fruntime\u002Fhotl-rt` and `.\u002Fscripts\u002F`\n\nThe same resolution applies to all HOTL scripts under `scripts\u002F`.\n\n**Dependency: `jq`.** `hotl-rt` requires `jq` for JSON state management. If `hotl-rt` fails with a `jq not found` error:\n1. Show the user the platform-specific install command from the error output\n2. Fall back to inline execution — run steps with per-step chat logs and manual checkbox updates, but without state persistence (`.hotl\u002Fstate\u002F`), durable reports (`.hotl\u002Freports\u002F`), or deterministic summary rendering\n3. Note in the final output that the run was not state-managed due to missing `jq`\n\n## Execution Report\n\nExecution report output must conform to `docs\u002Fcontracts\u002Fexecution-report-output.md`. The contract defines the durable report format (metadata, summary table, event log), execution status vocabulary, final summary semantics, platform rendering tables, and the deterministic renderer reference.\n\nThe `hotl-rt` runtime writes the durable report to `.hotl\u002Freports\u002F\u003Crun-id>.md` incrementally. The report survives app rendering quirks and provides a reliable post-run artifact for debugging, trust, and resume.\n\nReference `report_path` in user-facing pause, blocked, resume, and completion responses so the durable report is always discoverable.\n\nWhen a `verify: human-review` step pauses, the response must include the `report_path` and make it clear that the run is paused pending approval, not failed.\n\nIf the workflow sets `report_detail: full`, successful verify output must also be included in the durable report, not only failures.\n\n## Review Checkpoints\n\nRecord `git rev-parse HEAD` as the review base at run start and after each review.\n\n### At Final Completion\n\nAfter all steps have passed verification, before `hotl-rt finalize`:\n1. A final review is required unless the most recent review already covers all current changes and no code changed afterward\n2. Invoke `requesting-code-review` with review type: final\n   - Review base: branch point or last review base, whichever is more recent\n3. When findings return, invoke `receiving-code-review`\n   - Follow Verify → Evaluate → Respond → Implement\n4. Resolve all BLOCK findings before finalizing\n5. If fixes after the last review changed scope, constraints, or risk_level, request a scoped follow-up review before completing\n\n### At Intermediate Gates (Conditional)\n\nAt intermediate `gate: human` steps, request review only when:\n- risk_level is high\n- The gate covers cross-module or feature-scale changes\n- Multiple steps have completed since the last review\n\nWhen triggered, scope the review to steps completed since the last review checkpoint, not the entire run. Use review type: checkpoint.\n\nDo not request review at every gate by default.\n\n### Review Ordering\n\nReview happens:\n1. After step verification is complete\n2. Before `verification-before-completion`\n3. Before `hotl-rt finalize` \u002F any \"done\" claim\n\n## Safety Rules\n\n- `risk_level: high` in frontmatter **always** forces human approval at `gate: human` steps, even if `auto_approve: true`\n- Never skip a `gate: human` on steps with security-sensitive keywords (auth, encrypt, secret, key, password, token, permission, role, billing)\n- On STOP: always show the failing verify output so human can diagnose\n\n## Live Execution Behavior\n\nReport format, status vocabulary, final summary semantics, and platform rendering tables for final artifacts are defined in `docs\u002Fcontracts\u002Fexecution-report-output.md`. This section covers runtime behavior that is executor-owned: live step visibility, progress updates, and verbose mode.\n\n### Final Summary (mandatory)\n\nEvery execution run MUST end with a visible final summary in chat. A prose recap alone is not compliant.\n\nFor Codex final summaries:\n- MUST use `scripts\u002Ffinalize-codex-summary.sh` when available\n- MUST include the rendered compact list in the final response as visible chat text\n- MUST keep the rendered step lines intact; do not paraphrase, omit, or replace them with narrative\n- MAY add a short prose recap after the rendered summary, but not instead of it\n\nIf the Codex helper is unavailable, fall back to `hotl-rt finalize --json` plus `scripts\u002Frender-execution-summary.sh --platform codex ...`, then emit that renderer output directly.\n\n### Platform Rendering\n\nFinal artifacts must follow `docs\u002Fcontracts\u002Fexecution-report-output.md`:\n\n| Platform | Final summary rendering |\n|---|---|\n| Codex | Compact list in chat. Wide markdown tables are not acceptable here. |\n| Claude Code | Markdown table in chat. |\n| Cline | Markdown table in chat. |\n\nStatus vocabulary for final summaries includes `✓ Done`, `⚡ Auto-approved`, `✓ Approved`, `✗ Failed`, and `✗ Blocked`.\n\nIterations means attempt count only. For tables, the `Iterations` column is a number only or `-` for gates. Never put test counts in `Iterations`; test counts belong in `Status`.\n\nIn the Codex compact list, keep the step name first and inline status detail after ` - `. Include the status word on every line and always include iteration count details such as `Done (1 attempt)`, `Done (3 attempts)`, or `Approved (1 attempt)`.\n\n### Platform Live Step Visibility\n\n| Platform | Live step visibility |\n|---|---|\n| Codex | Native progress card (primary). Per-step chat logs as fallback. |\n| Claude Code | Per-step one-line chat logs |\n| Cline | Per-step one-line chat logs |\n\n### Live Step Visibility (mandatory)\n\nEvery execution run MUST provide live step visibility — the user must see which step is currently executing and which are done. This is not optional on any platform.\n\n### Codex Native Progress (mandatory with fallback)\n\nWhen running in the Codex app, the executor MUST use the native plan\u002Fprogress UI as the primary live step visibility surface:\n\n- MUST initialize the native progress card immediately after run setup (step 4 of the state machine)\n- MUST update it on every step transition — exactly one step `in_progress` at a time\n- MUST keep the native card high-level: major workflow steps only, not retries or verify substeps\n- If the native progress tool is unavailable or errors, MUST immediately switch to per-step chat logs for the remainder of the run. Do not silently drop visibility.\n- Native progress never replaces the final chat summary, durable report, or sidecar state\n- If Codex needs an explicit readout of the active workflow step, use `scripts\u002Fshow-codex-current-step.sh` to print the current step number, name, status, and attempts from the active run without mutating state\n\nOn platforms without native progress (Claude Code, Cline), the executor MUST use per-step chat logs for live visibility.\n\n### Per-Step Log (default, always shown)\n\nAfter each step, log one line:\n```\n✓ Step 1: Write failing tests\n✓ Step 2: Implement auth logic (3 attempts)\n⚡ Step 3: Security review gate (auto-approved)\n✓ Step 4: Update docs\n```\n\n### Verbose Progress View (opt-in)\n\nWhen verbose mode is enabled, print a compact step list at each step transition (before starting a step, after a step completes\u002Ffails\u002Fauto-approves):\n\n```\n  ✓ Step 1: Write failing tests\n  ✓ Step 2: Implement feature\n  → Step 3: Run full test suite (attempt 1\u002F3)\n  · Step 4: Update docs\n  · Step 5: Human review\n```\n\n**Symbols:**\n- `✓` — completed\n- `→` — current step (include attempt info if looping)\n- `·` — pending\n- `⚡` — auto-approved gate\n- `✗` — blocked\u002Ffailed\n\nInclude short result details only when useful (test counts on completed steps, attempt progress on current step, failure reason on blocked steps).\n\n### Verbose Mode Precedence\n\n1. **Executor invocation override wins** — user says \"run with verbose progress\"\n2. **Workflow frontmatter** — `progress: verbose`\n3. **Default** — non-verbose (per-step log only, no full list)\n\n## What to Do If No Workflow Found\n\nIf no canonical `docs\u002Fplans\u002F*-workflow.md` or legacy `hotl-workflow*.md` is found:\n\"No workflow file found. Would you like to:\n1. Create one from a design doc (`$hotl:writing-plans` in Codex, `\u002Fhotl:write-plan` in Claude Code)\n2. Use a workflow template from the plugin (`workflows\u002Ffeature.md`, `workflows\u002Fbugfix.md`, `workflows\u002Frefactor.md`)\"\n","# HOTL Loop Execution\n\n## Overview\n\nExecute an existing HOTL workflow file autonomously. Canonical workflows live at `docs\u002Fplans\u002FYYYY-MM-DD-\u003Cslug>-workflow.md`, with legacy root `hotl-workflow-\u003Cslug>.md` still accepted during migration. Loop on steps with success criteria. Auto-approve low-risk gates. Always pause for high-risk gates.\n\n`governed-execution` is the preferred new router for host-native or fallback runs. This skill remains the canonical autonomous state machine and a supported explicit compatibility profile. When invoked through the router, use the selected driver for lifecycle calls and require a sufficient evidence receipt before completion.\n\n**Announce:** \"Starting HOTL loop execution. Looking for workflow file...\"\n\n## Workflow File Resolution\n\nResolve which workflow file to execute:\n\n1. If the user specified a filename → use that file\n2. Else, glob for canonical workflows in `docs\u002Fplans\u002F*-workflow.md`:\n   - **One match** → use it automatically\n   - **Multiple matches** → if one is clearly the newest revision for the same semantic slug, prefer it; otherwise list them and ask the user to pick\n3. If no canonical matches, glob for legacy `hotl-workflow*.md` in project root:\n   - **One match** → use it automatically\n   - **Multiple matches** → list them and ask the user to pick\n4. **No matches** → see \"What to Do If No Workflow Found\" below\n\n### Interrupted Run Detection\n\nAfter resolving the workflow file, locate interrupted runs **before** Branch\u002FWorktree Preflight. Use `scripts\u002Fhotl-locate-run.sh --workflow \u003Cworkflow-file>` when available. This helper scans the current checkout, linked git worktrees, and HOTL's default `.hotl-worktrees\u002F\u003Crepo>\u002F` directory, so it can find state created inside an isolated execution worktree even when the new session starts from the authoring checkout.\n\nIf the helper is unavailable, manually scan these locations for `.hotl\u002Fstate\u002F*.json` and match `workflow_path` or `source_workflow_path` against the resolved workflow:\n1. Current checkout\n2. `git worktree list --porcelain` roots for the repo\n3. `$(dirname \u003Crepo-root>)\u002F.hotl-worktrees\u002F$(basename \u003Crepo-root>)\u002F*`\n\n- **One interrupted run found** → ask: \"Found an interrupted run (step N\u002FM). Resume from step N, or start fresh?\"\n- **Multiple interrupted runs found** → list all with run_id, step progress, branch, age. Ask which to resume or start fresh. **Never silently choose.**\n- **No interrupted runs** → proceed normally (new run)\n\nIf the user chooses resume, do not run Branch\u002FWorktree Preflight again. Load the matched sidecar, change into its recorded `execution_root`, and follow `skills\u002Fresuming\u002FSKILL.md` with the original `run_id`.\n\n## Branch\u002FWorktree Preflight\n\nAfter resolving the workflow file, run this preflight **before executing any steps**:\n\n```\n1. Is this a git repo with at least one commit?\n   - No  → log \"Skipping branch setup (no git history)\" → proceed to step execution\n   - Yes → continue\n\n2. Check for uncommitted changes\n   - First, exclude HOTL-owned transient artifacts from the dirty check:\n     • docs\u002Fplans\u002F*-workflow.md (canonical workflow files)\n     • hotl-workflow-*.md (legacy workflow files)\n     • docs\u002Fdesigns\u002F*.md (canonical design docs from brainstorming)\n     • docs\u002Fplans\u002F*-design.md, docs\u002Fplans\u002F*-plan.md (legacy design docs from brainstorming)\n     • .hotl\u002F (runtime state, reports, cache)\n   - If only HOTL artifacts are dirty → treat as clean, continue\n   - If non-HOTL dirty files exist:\n     • If dirty_worktree: allow in workflow frontmatter → proceed without prompting\n     • Otherwise → HARD-FAIL. Tell the user which non-HOTL files are dirty. Offer choices:\n       a. Clean up manually, then re-run\n       b. Stash manually, then re-run\n       c. Explicitly approve HOTL to stash and continue\n   - Clean → continue\n\n3. Determine branch name\n   - If branch: field exists in workflow frontmatter → use it\n   - Otherwise → derive `hotl\u002F\u003Cslug>` from the workflow filename\n     • Canonical: strip `YYYY-MM-DD-` prefix and `-workflow.md` suffix from `docs\u002Fplans\u002FYYYY-MM-DD-\u003Cslug>-workflow.md`\n     • Legacy: strip `hotl-workflow-` prefix and `.md` suffix from `hotl-workflow-\u003Cslug>.md`\n\n4. Capture authoring origin\n   - Record the current branch name (if any) and current `HEAD` commit as the workflow's authoring origin\n   - If the current branch is neither `main` nor `master`, and the workflow frontmatter does not already set `branch:` or `worktree:`, PAUSE and ask:\n     a. Continue on the current branch in this checkout\n        → set `branch: \u003Ccurrent-branch>` and `worktree: false`\n     b. Use HOTL's isolated execution branch\u002Fworktree (recommended)\n        → leave `worktree: true` and let HOTL derive `hotl\u002F\u003Cslug>` unless the user wants a custom branch name\n     c. Use a custom execution branch\n        → set `branch: \u003Cuser-branch>` and keep worktree isolation unless the user explicitly opts out\n   - Explain clearly: the authoring checkout and the execution checkout can differ. HOTL can execute in a separate worktree while leaving the current checkout untouched\n\n5. Determine isolation mode\n   - 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`\n   - If `worktree: false` in frontmatter → stay in the current checkout and use a dedicated branch there\n   - 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\n   - Otherwise → use an isolated git worktree by default\n\n6. Check if the target branch\u002Fworktree already exists locally\n   - Current helper behavior: existing branch\u002Fworktree collisions are a hard stop, not an interactive reuse\u002Frecreate flow\n   - If the helper reports an existing branch\u002Fworktree conflict, stop and ask the user whether to reuse manually, delete+recreate manually, or abort\n   - Does not exist → create (no prompt)\n\n7. Resolve the execution root with `scripts\u002Fhotl-prepare-execution-root.sh \u003Cworkflow-file> --executor-mode \u003Cmode>`\n   - The helper returns JSON with: `branch`, `repo_root`, `execution_root`, `workflow_path`, `source_workflow_path`, `source_branch`, `source_head`, `worktree_path`\n   - 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`\n   - If `worktree: false` in frontmatter → create\u002Fswitch to the dedicated branch in the current checkout and return the repo root as `execution_root`\n   - 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\n   - 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\n8. Change into `execution_root`\n   - Every later git command, runtime call, Codex helper call, and review command for this run MUST execute from that directory\n```\n\n**Rules:**\n- No auto-stash. Hidden state mutation weakens governance.\n- Existing branch\u002Fworktree collisions do not currently auto-prompt; treat them as a stop-and-ask condition until interactive reuse\u002Frecreate is implemented.\n- Non-git repos skip entirely — HOTL works without git ceremony.\n- Run HOTL structural lint (`scripts\u002Fdocument-lint.sh`) automatically on the workflow file before any git mutation or step execution. If lint fails, STOP and show all errors. If lint passes, continue silently.\n\n## HOTL Execution State Machine\n\nThis is the canonical HOTL execution state machine. Other execution modes (e.g., subagent-execution) reference this spec and define only their differences.\n\n```\n1. Resolve workflow file (see above)\n2. Parse frontmatter: intent, risk_level, auto_approve, branch, worktree\n3. Run Branch\u002FWorktree Preflight (see above)\n4. Capture preflight metadata and change into `execution_root`\n5. Initialize and claim the run via runtime:\n   - Run: `hotl-rt init \u003Cworkflow-file> --require-owner --executor-mode loop --repo-root \u003Crepo-root> --execution-root \u003Cexecution-root> --source-workflow-path \u003Csource-workflow-path> --source-branch \u003Csource-branch|null> --source-head \u003Csource-head|null> --worktree-path \u003Cworktree-path|null> --branch \u003Cbranch>`\n   - This parses the workflow, creates .hotl\u002Fstate\u002F\u003Crun-id>.json with all steps, and initializes .hotl\u002Freports\u002F\u003Crun-id>.md\n   - Capture the run_id from stdout\n   - Immediately run `hotl-rt owner claim --owner \u003Cstable-controller-id> --lease-seconds \u003Cbounded-lease> --run-id \u003Crun-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.\n   - Run `hotl-rt owner heartbeat --lease-seconds \u003Cbounded-lease> --run-id \u003Crun-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.\n   - 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 \u003Crun-id>` or set `HOTL_RUN_ID=\u003Crun-id>` for all runtime and helper calls.\n   - Never let the runtime silently choose \"the newest run\" when multiple runs exist\n   - Only after init and `owner claim` succeed should chat output or native plan\u002Fprogress UI show anything\n\n6. For each step in order:\n\n   a. Start step via runtime:\n      - Run: `hotl-rt step N start --run-id \u003Crun-id>`\n      - This persists step start (status, timestamp, attempts) to state and report\n      - Only after the runtime call succeeds should chat show \"→ Step N\"\n\n   b. Announce: \"→ Step N: [name]\"\n\n   c. Execute the action (agent implements the work)\n      - Heartbeat immediately before starting and after returning from any action that may run for a meaningful fraction of the lease.\n      - 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.\n      - For `external_write`, `production_change`, or `secret_access`, first run `hotl-rt action request \u003Ckind> --target \u003Cbounded-target> --idempotency-key \u003Cstable-key> --run-id \u003Crun-id>`, obtain the required human decision with `action decide`, then persist intent with `action begin \u003Caction-id> --idempotency-key \u003Cstable-key> --run-id \u003Crun-id>` before performing the effect.\n      - After observing the effect, run `action complete \u003Caction-id> \u003Csucceeded|failed|cancelled> --evidence-ref \u003Creference> --run-id \u003Crun-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.\n\n   d. Verify via runtime:\n      - Run: `hotl-rt step N verify --run-id \u003Crun-id>`\n      - The runtime runs the verify command, captures stdout\u002Fstderr, and atomically transitions the step to done or failed\n      - If the verify type is unsupported, the runtime blocks the step with a clear reason\n      - 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.\n      - 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)\n      - 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\u002F*` is invalid and should be authored as `path: src`\n      - 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 \u003Crun-id>` when external agent or cost telemetry was recorded or before launching another costly\u002Flong action.\n\n   e. If verify fails (runtime returns non-zero):\n\n      e0. If the runtime output says `blocked: human review required: ...`\n         → PAUSE immediately. Do not start later steps or finalize the run.\n         → Show the review prompt to the human and ask: \"Continue? (yes\u002Fno\u002Fshow-details)\"\n         → If the human says yes\u002Fapprove\u002Fcontinue:\n             Run: `hotl-rt gate N approved --mode human --run-id \u003Crun-id>`\n             Then continue to the next step\n         → If the human says no\u002Freject:\n             Run: `hotl-rt gate N rejected --mode human --run-id \u003Crun-id>`\n             STOP and surface the report path\n         → If the human asks for details:\n             Show the relevant test\u002Freport context, then wait again\n         → Never treat the chat reply alone as persisted approval; the approval is only real after the `hotl-rt gate ...` call succeeds\n\n      f. If loop: false\n         → STOP, report to human\n         → Run: `hotl-rt step N block --reason \"verify failed\" --run-id \u003Crun-id>` if not already marked failed by verify\n         → Show last verify output. Wait for human guidance.\n\n      g. If loop: until [condition]\n         → if iterations \u003C max_iterations:\n             Run: `hotl-rt step N retry --run-id \u003Crun-id>` then `hotl-rt step N start --run-id \u003Crun-id>`\n             log \"↻ Retrying ([n]\u002F[max])...\", retry the action\n         → if iterations = max_iterations: STOP\n             Report: \"Step N reached max iterations ([max]). [condition] not met.\"\n             Show last verify output. Wait for human guidance.\n\n      h. On step completion (verify passed):\n      - The runtime has already persisted the done status\n      - Update the workflow checkbox to [x]\n      - Only after the runtime confirms success should chat show \"✓ Step N\"\n\n   i. If gate: human\n      → if auto_approve: true AND risk_level != high:\n          Run: `hotl-rt gate N approved --mode auto --run-id \u003Crun-id>`\n          log \"⚡ Auto-approved: Step N gate (risk: [risk_level])\"\n          continue\n      → else:\n          PAUSE. Show summary of what was done in this step.\n          Ask: \"Gate reached at Step N. Continue? (yes\u002Fno\u002Fshow-details)\"\n          Wait for human response.\n          Run: `hotl-rt gate N approved --mode human --run-id \u003Crun-id>` or `hotl-rt gate N rejected --mode human --run-id \u003Crun-id>`\n\n   j. If gate: auto\n      → Run: `hotl-rt gate N approved --mode auto --run-id \u003Crun-id>`\n      → always continue, log \"⚡ Auto-approved: Step N gate\"\n\n7. All steps complete:\n   → Run review checkpoint (see Review Checkpoints below)\n   → Invoke hotl:verification-before-completion skill\n   → For Codex final summaries, run: `scripts\u002Ffinalize-codex-summary.sh \u003Crun-id>` (or set `HOTL_RUN_ID`)\n   → For Claude Code\u002FCline, run: `hotl-rt finalize --json --run-id \u003Crun-id>`, write the payload to a temp file, then render it with: `scripts\u002Frender-execution-summary.sh --platform \u003Cclaude|cline> \u003Csummary-json-file>`\n   → Successful finalize sets status to `ready_to_finish`, not `completed`. It proves step\u002Fgate\u002Feffect\u002Fbudget readiness but does not invent a branch disposition.\n   → Do not freehand the final summary when the renderer is available\n   → 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.\n   → Never silently merge, publish, keep, or discard the execution branch\u002Fworktree\n   → After `hotl-rt finish` moves a successful run from `ready_to_finish` to `completed`, run `owner release`, then require `hotl-rt receipt \u003Crun-id> --json` to report `sufficiency.sufficient: true`.\n   → Only then show the rendered summary as visible chat output in the final response; do not paraphrase it away or claim completion earlier.\n```\n\n## Execution State Persistence\n\nAll state persistence is handled by the `hotl-rt` shared runtime (`runtime\u002Fhotl-rt`). Agents do not manage state files directly.\n\nThe runtime owns:\n- `.hotl\u002Fstate\u002F\u003Crun-id>.json` — authoritative machine state (created by `hotl-rt init`, updated by owner\u002Fstep\u002Fgate\u002Faction\u002Fbudget\u002Ffinalize\u002Ffinish transitions)\n- `.hotl\u002Freports\u002F\u003Crun-id>.md` — durable Markdown report (initialized at init, updated incrementally, finalized at finalize)\n\nThe sidecar also records the execution location for the run: `repo_root`, `execution_root`, `workflow_path`, `source_workflow_path`, `worktree_path`, and `executor_mode`.\n\nRun ID format: `\u003Cslug>-\u003CYYYYMMDDTHHMMSSZ>-\u003C12-hex-nonce>` (e.g., `add-auth-20260320T212315Z-a1b2c3d4e5f6`). The entropy suffix prevents collisions across independent execution roots; legacy timestamp-only IDs remain readable.\n\nWorkflow checkboxes (`- [x]`) are a human-visible mirror updated by the agent on step completion. The sidecar is the source of truth.\n\nOperational rule: `hotl-rt` calls happen before the corresponding chat log or Codex native plan\u002Fprogress update. Native progress UI is never a substitute for the runtime-managed artifacts.\n\nConcurrency rule: after `hotl-rt init` returns a run id, claim the renewable controller and pin every later runtime\u002Fhelper call to that run id with `HOTL_OWNER_TOKEN`. Do not rely on \"latest file in .hotl\u002Fstate\" when more than one run exists, and do not use file age as takeover authority.\n\nSee `skills\u002Fresuming\u002FSKILL.md` for the full sidecar schema, stale run detection, and verify-first resume flow.\n\n### Path Resolution\n\nTo find `hotl-rt` and HOTL scripts (`document-lint.sh`, `hotl-locate-run.sh`, `render-execution-summary.sh`, etc.), resolve in this order:\n\n1. **Session context (Claude Code):** the session-start hook injects the plugin base path — use it to construct full paths like `bash \u003Cplugin-path>\u002Fruntime\u002Fhotl-rt init \u003Cworkflow-file>`\n2. **Codex native-skills install:** resolve from `~\u002F.codex\u002Fhotl\u002Fruntime\u002Fhotl-rt` and `~\u002F.codex\u002Fhotl\u002Fscripts\u002F`\n3. **Codex plugin install:** resolve from `~\u002F.codex\u002Fplugins\u002Fhotl-source\u002Fruntime\u002Fhotl-rt` and `~\u002F.codex\u002Fplugins\u002Fhotl-source\u002Fscripts\u002F`\n4. **Codex plugin cache fallback:** resolve from `~\u002F.codex\u002Fplugins\u002Fcache\u002Fcodex-plugins\u002Fhotl\u002F*\u002Fruntime\u002Fhotl-rt` and `~\u002F.codex\u002Fplugins\u002Fcache\u002Fcodex-plugins\u002Fhotl\u002F*\u002Fscripts\u002F`\n5. **Cline:** resolve from `~\u002FDocuments\u002FCline\u002FScripts\u002Fhotl-rt` and `~\u002FDocuments\u002FCline\u002FScripts\u002F`\n6. **Working in the hotl-plugin repo itself:** use `.\u002Fruntime\u002Fhotl-rt` and `.\u002Fscripts\u002F`\n\nThe same resolution applies to all HOTL scripts under `scripts\u002F`.\n\n**Dependency: `jq`.** `hotl-rt` requires `jq` for JSON state management. If `hotl-rt` fails with a `jq not found` error:\n1. Show the user the platform-specific install command from the error output\n2. Fall back to inline execution — run steps with per-step chat logs and manual checkbox updates, but without state persistence (`.hotl\u002Fstate\u002F`), durable reports (`.hotl\u002Freports\u002F`), or deterministic summary rendering\n3. Note in the final output that the run was not state-managed due to missing `jq`\n\n## Execution Report\n\nExecution report output must conform to `docs\u002Fcontracts\u002Fexecution-report-output.md`. The contract defines the durable report format (metadata, summary table, event log), execution status vocabulary, final summary semantics, platform rendering tables, and the deterministic renderer reference.\n\nThe `hotl-rt` runtime writes the durable report to `.hotl\u002Freports\u002F\u003Crun-id>.md` incrementally. The report survives app rendering quirks and provides a reliable post-run artifact for debugging, trust, and resume.\n\nReference `report_path` in user-facing pause, blocked, resume, and completion responses so the durable report is always discoverable.\n\nWhen a `verify: human-review` step pauses, the response must include the `report_path` and make it clear that the run is paused pending approval, not failed.\n\nIf the workflow sets `report_detail: full`, successful verify output must also be included in the durable report, not only failures.\n\n## Review Checkpoints\n\nRecord `git rev-parse HEAD` as the review base at run start and after each review.\n\n### At Final Completion\n\nAfter all steps have passed verification, before `hotl-rt finalize`:\n1. A final review is required unless the most recent review already covers all current changes and no code changed afterward\n2. Invoke `requesting-code-review` with review type: final\n   - Review base: branch point or last review base, whichever is more recent\n3. When findings return, invoke `receiving-code-review`\n   - Follow Verify → Evaluate → Respond → Implement\n4. Resolve all BLOCK findings before finalizing\n5. If fixes after the last review changed scope, constraints, or risk_level, request a scoped follow-up review before completing\n\n### At Intermediate Gates (Conditional)\n\nAt intermediate `gate: human` steps, request review only when:\n- risk_level is high\n- The gate covers cross-module or feature-scale changes\n- Multiple steps have completed since the last review\n\nWhen triggered, scope the review to steps completed since the last review checkpoint, not the entire run. Use review type: checkpoint.\n\nDo not request review at every gate by default.\n\n### Review Ordering\n\nReview happens:\n1. After step verification is complete\n2. Before `verification-before-completion`\n3. Before `hotl-rt finalize` \u002F any \"done\" claim\n\n## Safety Rules\n\n- `risk_level: high` in frontmatter **always** forces human approval at `gate: human` steps, even if `auto_approve: true`\n- Never skip a `gate: human` on steps with security-sensitive keywords (auth, encrypt, secret, key, password, token, permission, role, billing)\n- On STOP: always show the failing verify output so human can diagnose\n\n## Live Execution Behavior\n\nReport format, status vocabulary, final summary semantics, and platform rendering tables for final artifacts are defined in `docs\u002Fcontracts\u002Fexecution-report-output.md`. This section covers runtime behavior that is executor-owned: live step visibility, progress updates, and verbose mode.\n\n### Final Summary (mandatory)\n\nEvery execution run MUST end with a visible final summary in chat. A prose recap alone is not compliant.\n\nFor Codex final summaries:\n- MUST use `scripts\u002Ffinalize-codex-summary.sh` when available\n- MUST include the rendered compact list in the final response as visible chat text\n- MUST keep the rendered step lines intact; do not paraphrase, omit, or replace them with narrative\n- MAY add a short prose recap after the rendered summary, but not instead of it\n\nIf the Codex helper is unavailable, fall back to `hotl-rt finalize --json` plus `scripts\u002Frender-execution-summary.sh --platform codex ...`, then emit that renderer output directly.\n\n### Platform Rendering\n\nFinal artifacts must follow `docs\u002Fcontracts\u002Fexecution-report-output.md`:\n\n| Platform | Final summary rendering |\n|---|---|\n| Codex | Compact list in chat. Wide markdown tables are not acceptable here. |\n| Claude Code | Markdown table in chat. |\n| Cline | Markdown table in chat. |\n\nStatus vocabulary for final summaries includes `✓ Done`, `⚡ Auto-approved`, `✓ Approved`, `✗ Failed`, and `✗ Blocked`.\n\nIterations means attempt count only. For tables, the `Iterations` column is a number only or `-` for gates. Never put test counts in `Iterations`; test counts belong in `Status`.\n\nIn the Codex compact list, keep the step name first and inline status detail after ` - `. Include the status word on every line and always include iteration count details such as `Done (1 attempt)`, `Done (3 attempts)`, or `Approved (1 attempt)`.\n\n### Platform Live Step Visibility\n\n| Platform | Live step visibility |\n|---|---|\n| Codex | Native progress card (primary). Per-step chat logs as fallback. |\n| Claude Code | Per-step one-line chat logs |\n| Cline | Per-step one-line chat logs |\n\n### Live Step Visibility (mandatory)\n\nEvery execution run MUST provide live step visibility — the user must see which step is currently executing and which are done. This is not optional on any platform.\n\n### Codex Native Progress (mandatory with fallback)\n\nWhen running in the Codex app, the executor MUST use the native plan\u002Fprogress UI as the primary live step visibility surface:\n\n- MUST initialize the native progress card immediately after run setup (step 4 of the state machine)\n- MUST update it on every step transition — exactly one step `in_progress` at a time\n- MUST keep the native card high-level: major workflow steps only, not retries or verify substeps\n- If the native progress tool is unavailable or errors, MUST immediately switch to per-step chat logs for the remainder of the run. Do not silently drop visibility.\n- Native progress never replaces the final chat summary, durable report, or sidecar state\n- If Codex needs an explicit readout of the active workflow step, use `scripts\u002Fshow-codex-current-step.sh` to print the current step number, name, status, and attempts from the active run without mutating state\n\nOn platforms without native progress (Claude Code, Cline), the executor MUST use per-step chat logs for live visibility.\n\n### Per-Step Log (default, always shown)\n\nAfter each step, log one line:\n```\n✓ Step 1: Write failing tests\n✓ Step 2: Implement auth logic (3 attempts)\n⚡ Step 3: Security review gate (auto-approved)\n✓ Step 4: Update docs\n```\n\n### Verbose Progress View (opt-in)\n\nWhen verbose mode is enabled, print a compact step list at each step transition (before starting a step, after a step completes\u002Ffails\u002Fauto-approves):\n\n```\n  ✓ Step 1: Write failing tests\n  ✓ Step 2: Implement feature\n  → Step 3: Run full test suite (attempt 1\u002F3)\n  · Step 4: Update docs\n  · Step 5: Human review\n```\n\n**Symbols:**\n- `✓` — completed\n- `→` — current step (include attempt info if looping)\n- `·` — pending\n- `⚡` — auto-approved gate\n- `✗` — blocked\u002Ffailed\n\nInclude short result details only when useful (test counts on completed steps, attempt progress on current step, failure reason on blocked steps).\n\n### Verbose Mode Precedence\n\n1. **Executor invocation override wins** — user says \"run with verbose progress\"\n2. **Workflow frontmatter** — `progress: verbose`\n3. **Default** — non-verbose (per-step log only, no full list)\n\n## What to Do If No Workflow Found\n\nIf no canonical `docs\u002Fplans\u002F*-workflow.md` or legacy `hotl-workflow*.md` is found:\n\"No workflow file found. Would you like to:\n1. Create one from a design doc (`$hotl:writing-plans` in Codex, `\u002Fhotl:write-plan` in Claude Code)\n2. Use a workflow template from the plugin (`workflows\u002Ffeature.md`, `workflows\u002Fbugfix.md`, `workflows\u002Frefactor.md`)\"\n",{"name":5,"description":7},"main","2b63f856ce19c2a797929cacabd9e0fc936812fa","plugins\u002Fyimwoo\u002Fhotl-plugin\u002Fskills\u002Floop-execution",491,"https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins","https:\u002F\u002Fhol.org\u002Fplugins\u002Fbest-codex-plugins","https:\u002F\u002Fgithub.com\u002Fhashgraph-online","https:\u002F\u002Fhol.org","Open-source standards and developer tools for interoperable AI agents: discovery, identity, communication, payments, privacy and security.","2026-11-14 14:06:13",{"source":8,"skillName":5,"commands":50,"prompt":60,"zipAvailable":61},[51,54,57],{"tool":52,"command":53},"npx","npx skills add hashgraph-online\u002Fawesome-codex-plugins --skill loop-execution",{"tool":55,"command":56},"bunx","bunx skills add hashgraph-online\u002Fawesome-codex-plugins --skill loop-execution",{"tool":58,"command":59},"pnpm","pnpm dlx skills add hashgraph-online\u002Fawesome-codex-plugins --skill loop-execution","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fyimwoo\u002Fhotl-plugin\u002Fskills\u002Floop-execution\u002FSKILL.md",true,[],[64,72,78,84,91,98],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":71},"01M7470B0PGPN5JMTGNHMADK7E","zenifra","Use when the user wants to manage Zenifra projects, profiles, organizations, deployments, builds, authentication, or supported Git providers from Codex.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fzenifra\u002Fzenifra-codex-plugin\u002Fskills\u002Fzenifra\u002FSKILL.md",[],[],"2026-11-11 15:11:14",{"skillNo":73,"name":74,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":71},"01M746KVM5M3ZB2441VP5TKPJY","hyper-review","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Falpoxdev\u002Fhypercore\u002Fskills\u002Fhyper-review\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":81,"categories":82,"keywords":83,"publishedAt":71},"01M746KHKQ1SC0KAHVFS68T808","hyper-debate","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Falpoxdev\u002Fhypercore\u002Fskills\u002Fhyper-debate\u002FSKILL.md",[],[],{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":71},"01M746KC5CPM9XRQSDTT8BPG8W","hyper-cleanup","Use this skill when someone asks to clean up, delete, or consolidate code, tests, comments, or dead weight in a repository that already works, and the cleanup must not change behavior. It names each in-scope unit as a slop category or a keeper, walks a delete-reuse-platform-simplify ladder, locks behavior with a runnable baseline before the first edit, proves each test deletion or consolidation with a source mutation that is restored byte for byte, and writes a report under `.hyper\u002Fcleanup\u002F`. Do not use for authoring new behavior, refactoring a public API, migrating dependencies, or formatting a whole repository.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Falpoxdev\u002Fhypercore\u002Fskills\u002Fhyper-cleanup\u002FSKILL.md",[],[],{"skillNo":92,"name":93,"nameZh":6,"description":94,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":71},"01M746K1D7J4P0VAPJ78MXHB27","graymatter-onboarding","Welcome a new GrayMatter user, complete first-use setup, demonstrate a useful save-and-recall result, or recover an interrupted connection. Use for getting started, activation, setup, and requests to make GrayMatter primary agent memory.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FValkyrLabs\u002FGrayMatter\u002Fskills\u002Fgraymatter-onboarding\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":71},"01M746HAZ824PFSF2GE8C510Q4","risk-xva","Run a trusted local ORE (Open Source Risk Engine) project for counterparty exposure and valuation adjustments (risk_xva), and read its XVA and exposure reports. Use for ORE CVA, DVA, funding and other XVA reports, or to produce the netting-set exposure profile that risk_exposure_profile summarises. Not for historical VaR (use risk-tail), not for SA-CCR (use risk-counterparty), and not for a project you have not inspected.","https:\u002F\u002Fgithub.com\u002Fhashgraph-online\u002Fawesome-codex-plugins\u002Fblob\u002Fmain\u002Fplugins\u002FIman\u002Fagent-driven-risk-desk-and-skills\u002Fskills\u002Frisk-xva\u002FSKILL.md",[],[]]