halt-long-horizon-tasks

---
name: halt-long-horizon-tasks
description: "Use when a task may span sessions, get interrupted, or require resumable auditable progress. Runs long-horizon work under the HALT specification."
version: 1.0.0
platforms: [windows, linux, macos]
tags: [long-horizon, recovery, state-management, agents]
metadata:
  hermes:
    tags: [long-horizon, recovery, state-management, agents, workflow]
---

# HALT — Hierarchical Automaton for Long-horizon Tasks

A process specification for running long-horizon tasks with AI agents — interruptible at any point, persistently memorized, arbitrarily nestable. Source: HALT v1.0.2 specification, shipped verbatim under `spec/`.

> **The one-sentence model.** A task is a directed graph of nodes driven by journaled transactional state machines; progress exists only where write→verify→commit has completed; any agent — new or old, human or machine — resumes by asking *"where is my last provably stable position?"* and recomputing what may legally run next.

## When to apply

- Task will plausibly outlive the current session (multi-hour builds, batch jobs over many items, multi-phase research/writing pipelines).
- Environment can die without warning (crash, quota wall, closed window) and work must survive it.
- Work is delegated across parallel workers/subagents and claims must be verified against disk.
- A previous HALT-managed task exists on disk and must be resumed.

Skip for single-session, restart-cheap tasks (**Tier 0**: ceremony costs more than it saves).

## Non-negotiable core (the short form)

1. **Four persistent artifacts** per task workspace: `task-graph.json` (DAG + node states), `journal.jsonl` (append-only event log — the authoritative record), artifact registry + files under `artifacts/`, `checkpoint.json` (pointer cache). Everything else (`docs/`, `tmp/`) is a rebuildable view.
2. **Commit Rule**: a unit is DONE only after write→verify→commit, with evidence registered on disk. Claims without committed artifacts are not progress ("claim ≠ commit").
3. **Journal discipline**: append only; never rewrite earlier lines; derive `seq` as `1 + max(seq)` read from the tail immediately before each append batch — cached counters across restarts cause silent seq collisions (the worst failure mode).
4. **State transitions are legal only through the FSM tables** (`spec/02-lifecycle-fsm.md`) and must cite evidence refs. Illegal jumps and unevidenced DONE are defects.
5. **Recovery = recompute, do not hand-reconcile**: on any inconsistency between files, treat the journal as truth and run the R0–R7 procedure (`spec/05-recovery.md`). Never edit multiple files to "make them match".
6. **Escalation map**: every failure class gets a declared route; unmapped failures default to suspend-with-handoff-note + notify parent. Silent death propagation is forbidden.

Full normative text: start at `spec/00-index.md`.

## Operating procedure for a new long-horizon task

1. Create the workspace tree exactly as `spec/04-persistence-layout.md` §1 fixes it (top-level four artifacts + `contracts/ steering/ sops/ docs/ tmp/`). Paths are workspace-relative POSIX-style; IDs never encode absolute paths.
2. Decompose the goal into nodes small enough that any interruption costs at most its own unit of work; record acceptance criteria **with check methods** (script / audit / human) per node.
3. Pick the conformance tier (`spec/01-core-model.md` §9): Tier 1 default (full artifact set + commit rule + recovery); Tier 2 adds tx grouping, receipts everywhere, mirrored journals.
4. Execute node-by-node under the Commit Rule with heartbeats; journal every transition, decision, and amendment at the moment it happens.
5. Maintain `docs/task-plan.md`, `docs/progress.md`, and `docs/DOC-LEDGER.md` (working-doc register with purpose + minute-level mtime — undocumented temp files become archaeology puzzles after interruptions).
6. On resume (fresh session): locate last provably stable position from journal + checkpoint, recompute the legal frontier (`spec/02-lifecycle-fsm.md` §6), continue — never trust prose summaries or conversation memory alone.
7. Route human questions through the durable steering channel (`steering/inbox.md`) BEFORE waiting, so total session loss preserves what must be asked and why (`spec/09-human-gates-and-steering.md`).

## Reference runtime

`spec/runtime/halt_rt.py` (~460 lines, standard library only) implements the core mechanisms single-node: seq tail-derivation, atomic registry writes, same-path version inversion refusal, missing-artifact refusal, single-writer lease, FSM legality checks. Verify it first:

```bash
cd <skill-dir>/spec/runtime && python test_halt_rt.py   # expect: 8 passed
```

```python
import os
from halt_rt import HaltRuntime

rt = HaltRuntime(workspace, task_id="my-task")   # fresh workspace
# ... crash happens ...
rt = HaltRuntime.resume(workspace)               # rebuild from ledger

rt.add_node("N1", "do thing")
rt.transition("N1", "READY")
rt.transition("N1", "RUNNING")

# Artifact content must hit disk BEFORE registration (PD-J1: no disk, no DONE).
# Paths are workspace-relative (PL-4), so join them onto the workspace root:
out = os.path.join(workspace, "artifacts", "N1", "n1-out.md")
os.makedirs(os.path.dirname(out), exist_ok=True)
open(out, "w").write("node N1 output")

rt.register_artifact("A-N1", "artifacts/N1/n1-out.md", kind="doc", node_id="N1")
rt.transition("N1", "VERIFYING", evidence=["A-N1"])
rt.transition("N1", "DONE", evidence=["A-N1 verified"])

rt.steering("ST-001", "...")    # durable steering event
rt.decision("DR-1", "...")      # decision record
print(rt.status())              # seq/nodes/integrity at a glance
```

Scope: single-node, single-writer. Parallel fan-out, nesting, and cross-task memory map to HALT-06/07/10 and are currently manual disciplines per the spec chapters.

## Document map (all paths relative to this skill's directory)

| Doc | Read for |
|---|---|
| `spec/00-index.md` | Entry point & document map |
| `spec/01-core-model.md` | Axioms, definitions D1–D24, Commit Rule, side-effect classes S0–S3, invariants |
| `spec/02-lifecycle-fsm.md` | Node/task state machines, verification levels, frontier computation, retry matrix |
| `spec/03-sop-interface.md` | Uniform SOP card, invocation/result documents, failure escalation map |
| `spec/04-persistence-layout.md` | Canonical workspace tree, journal/checkpoint/graph/registry formats |
| `spec/05-recovery.md` | R0–R7 procedure, interruption taxonomy, checkpoint regeneration |
| `spec/06-nesting-composition.md` | Parent-child contracts, namespace isolation, failure containment |
| `spec/07-parallel-dispatch.md` | Slot accounting, adaptive modes, merge discipline |
| `spec/08-roles-and-authority.md` | Role partitions, grants, team patterns |
| `spec/09-human-gates-and-steering.md` | Durable steering inbox, approval gates, escalation bundles |
| `spec/10-memory-store.md` | Cross-task knowledge: working/memory boundary, freshness gate |
| `spec/11-conformance-and-derivations.md` | Self-audit checklist, limitations |
| `spec/12-validation-report.md` | Field-run incidents, amendments A-1..A-4, fixture map |
| `spec/glossary.md` | One authoritative definition per term |

Reading paths — implementer: 01→02→04→05→03; operator: 01 §1–2/§7, 09, 11 §C; skeptic: 05 §3, 11 §D.

## Notes

- The `zh/01-core-model.md` Chinese edition of the core document ships alongside (`spec/zh/`).
- The spec text under `spec/` is authoritative and versioned (v1.0.2); this SKILL.md is an operational entry layer and defers to it on any conflict.