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:

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

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.