Tasks: programmatic hooks around the lifecycle of a work item's delivery

The last spec artifact. Derived from design.md and testing-plan.md. Gate-less (issue-281): it advances on shape.

Execution DAG

Tasks

[x] 1 · The contract. cli/the_loop/lifecycle/contract.py: Context base with POINT, to_params, apply (decisions only, DecisionTypeError), decisions; the six contexts; LifecycleHooks with one method per point and handles; POINTS. Tests first in tests/test_lifecycle_contract.py, including the catalog ↔ base-class parity. Requirements: R1.1, R1.4, R2.1, R2.2, R2.4. Test: T1.
[x] 2 · The declaration. lifecycle/declaration.py: Entry, Declaration, read_declaration, HooksConfigError, path resolution against the config file's directory, the URL scheme rule. Tests in tests/test_lifecycle_declaration.py. Requirements: R3.1–R3.4, R4.3, abuse 1, 4, 8. Test: T2, T8.
[x] 3 · Executors and the loader. lifecycle/executors.py: Executor, LocalExecutor, load(declaration, base_dir) -> list[Executor] (module/path import, executor selection, with, cache). Requirements: R3.5, R4.1, abuse 6. Test: T3.
[x] 4 · The remote protocol. lifecycle/remote.py: RemoteExecutor (urllib, bearer from tokenEnv, timeout, JSON-RPC checks, HookFailure), handle_request, HookServer. Tests against a live server in tests/test_lifecycle_remote_integration.py. Requirements: R4.2–R4.4, abuse 2, 3, 5. Test: T5, T8.
[x] 5 · The runner and the seam. lifecycle/runner.py (Runner.run, the hooks.* events) and lifecycle/__init__.py (configure, configure_from_config, configure_from_file, run with lazy load, reset); EVENT_TYPES entries. Tests in tests/test_lifecycle_runner.py. Requirements: R2.3, R3.6, R3.7, R5.3, R6.1–R6.4, abuse 3, 6, 7. Test: T4, T8, T9.
[x] 6 · The dispatcher call sites. ControlStore.mark_started/clear_started and the lifecycle section; _spawn_for (work_item_start, refusal path, CONTROL_REFUSAL_REMEDIES["hook-refused"]); _before_launch/_after_launch in _spawn_tmux, _spawn_endpoint, _respawn_tmux; _record_closure (work_item_complete, clear_started). Requirements: R1.2, R2.6, R2.7, R7.1. Test: T6.
[x] 7 · The runtime and ask call sites. Runtime.start/advance (phase_changed gating _lifecycle; waiting_for_input for a human node); ask_session (waiting_for_input for the question). Requirements: R1.2, R2.7, R7.1. Test: T7.
[x] 8 · Daemons configure at start. Poller run, receiver run, service serve call lifecycle.configure_from_file(strict=True) and exit 1 on failure. Requirements: R3.6. Test: T4 (test_a_daemon_refuses_to_start_on_a_bad_declaration).
[x] 9 · the-loop hooks. commands/hooks_cmd.py: list (default) and points, text/json, strict read, no import. Tests in tests/test_hooks_cmd.py. Requirements: R5.1, R5.2. Test: T10.
[x] 10 · Integration scenarios. tests/test_lifecycle_hooks_integration.py: the Gherkin scenarios of T6/T7 over the real dispatcher, Runtime and ask_session. Requirements: R1.2, R2.6, R2.7, R7.1, R7.2. Test: T6, T7.
[x] 11 · Schema, samples, SDK. Top-level hooks in both schema copies; commented samples in .the-loop/cli-config.yaml and the template; the_loop/sdk/hooks.py. Requirements: R3.1, R4.5. Test: T9.
[x] 12 · Docs and decision. docs/cli/lifecycle-hooks.md, docs/config/cli/hooks-options.md, docs/cli/commands/hooks.md, docs/capabilities/lifecycle-hooks.md + index row, docs/sdk/reference.md section, sidebar, docs/cli/hooks.md and docs/config/cli/index.md cross-links, skills/the-loop/reference/automation.md, docs/decisions/decision-137.md + index row. Requirements: R1.4, R2.5. Test: T9, T13.
[x] 13 · Verify and record. Run T1–T11, T13; write evidence/verification.md, self-review.md, security-review.md, documentation.md; tick the plan's activities. Test: all.

Checkpoints

After tasks 5, 8 and 10: make test. After 12: make check. Each task's commit records its test command and the red→green transition.

Review comments

Appended by the-loop's record-feedback hook when a human gate approves with comments (issue-109). Append-only and attributed: an approval never silently discards a reviewer's suggestions, and the feedback travels with the document it concerns rather than living in a side-channel tracker.