@event4u/agent-config 1.14.0 → 1.16.0

package/.agent-src/templates/scripts/work_engine/delivery_state.py

@@ -1,6 +1,6 @@
 """``DeliveryState`` — the only object shared between orchestrator steps.
 
-The shape mirrors ``agents/contexts/implement-ticket-flow.md``. No step
+The shape mirrors ``docs/contracts/implement-ticket-flow.md``. No step
 may invent fields not declared here; extensions require a roadmap
 amendment plus a flow-contract update.
 
@@ -59,7 +59,7 @@ class DeliveryState:
     """Canonical state passed between orchestrator steps.
 
     Field order matches the table in
-    ``agents/contexts/implement-ticket-flow.md``. Mutable defaults use
+    ``docs/contracts/implement-ticket-flow.md``. Mutable defaults use
     ``field(default_factory=...)`` so every instance owns its own
     containers — a single shared list across runs would be a
     cross-run contamination hazard for the metrics pipeline.
@@ -103,7 +103,7 @@ skill; the user-facing numbered options follow on subsequent lines.
 
 The prefix is public contract: changing it breaks every agent that
 has learned to recognise it. See
-``agents/contexts/implement-ticket-flow.md#agent-directives``.
+``docs/contracts/implement-ticket-flow.md#agent-directives``.
 """
 
 

package/.agent-src/templates/scripts/work_engine/directives/backend/__init__.py

@@ -22,7 +22,7 @@ validate upstream state; the delegation gates (``plan``,
 matching skill and resume. ``report`` renders the delivery Markdown
 once everything else has succeeded. See
 ``agents/roadmaps/road-to-implement-ticket.md`` for the shipping
-order and ``agents/contexts/implement-ticket-flow.md`` for the
+order and ``docs/contracts/implement-ticket-flow.md`` for the
 slice contracts each handler writes to.
 """
 from __future__ import annotations

package/.agent-src/templates/scripts/work_engine/directives/backend/implement.py

@@ -17,7 +17,7 @@ Flow:
 - Otherwise → SUCCESS.
 
 ``changes`` entries use the loose shape described in
-``agents/contexts/implement-ticket-flow.md#deliverystate-the-only-shared-object``
+``docs/contracts/implement-ticket-flow.md#deliverystate-the-only-shared-object``
 \u2014 each entry is a dict with at least a ``path``; optional
 ``lines`` / ``purpose`` feed the delivery report.
 """

package/.agent-src/templates/scripts/work_engine/directives/backend/memory.py

@@ -1,7 +1,7 @@
 """``memory`` step — bounded retrieval over the four allowed types.
 
 Contract (see
-``agents/contexts/implement-ticket-flow.md#memory-retrieval-contract``):
+``docs/contracts/implement-ticket-flow.md#memory-retrieval-contract``):
 
 - Four allowed types: ``domain-invariants``, ``architecture-decisions``,
   ``incident-learnings``, ``historical-patterns``.

package/.agent-src/templates/scripts/work_engine/directives/backend/plan.py

@@ -3,7 +3,7 @@
 The dispatcher cannot synthesise a plan from pure Python: the real
 work needs code reading and judgement that only the agent has. The
 step therefore follows the Option-A delegation pattern described in
-``agents/contexts/implement-ticket-flow.md#agent-directives``:
+``docs/contracts/implement-ticket-flow.md#agent-directives``:
 
 - ``state.plan`` empty → halt with ``BLOCKED`` and emit
   ``@agent-directive: create-plan``. The orchestrator runs the

package/.agent-src/templates/scripts/work_engine/directives/backend/report.py

@@ -1,7 +1,7 @@
 """``report`` step — delivery report renderer.
 
 Produces the markdown block described in
-``agents/contexts/implement-ticket-flow.md#delivery-report-schema``.
+``docs/contracts/implement-ticket-flow.md#delivery-report-schema``.
 All nine headings are present on every run — the schema is stable
 for consumers — but section bodies are omitted when the matching
 slice of ``DeliveryState`` is empty. The single exception is the

package/.agent-src/templates/scripts/work_engine/dispatcher.py

@@ -1,7 +1,7 @@
 """Linear step dispatcher for ``/implement-ticket``.
 
 The dispatcher holds no business logic. It walks the fixed eight-step
-order declared in ``agents/contexts/implement-ticket-flow.md``, hands
+order declared in ``docs/contracts/implement-ticket-flow.md``, hands
 each step a live ``DeliveryState``, and honours the three terminal
 outcomes:
 

package/.agent-src/templates/scripts/work_engine/emitters.py

@@ -0,0 +1,43 @@
+"""Stdout / stderr emitters for the CLI entry point.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Holds the two output helpers that
+shape the wire surface of ``main()``: the SUCCESS/halt branch printed
+on stdout, and the lifecycle-hook halt surface printed on stderr.
+"""
+from __future__ import annotations
+
+import sys
+
+from .delivery_state import Outcome
+from .hooks import HookHalt
+from .state import WorkState
+
+
+def _emit(work: WorkState, final: Outcome, halting: str | None) -> None:
+    if final is Outcome.SUCCESS:
+        print(work.report)
+        return
+    print(f"[halt] outcome={final.value} step={halting or '(none)'}")
+    for line in work.questions:
+        print(line)
+
+
+def _emit_halt(halt: HookHalt) -> int:
+    """Render a :class:`HookHalt` surface to stderr and return exit 2.
+
+    Per the P3 halt branch table, every CLI-layer halt yields exit code
+    ``2`` regardless of which event fired it. State persistence is
+    governed by *where* in ``main`` the halt is detected: the call site
+    decides whether ``_save`` already ran. This helper is the single
+    place that formats the surface so the wire output stays consistent.
+    """
+    if halt.surface:
+        for line in halt.surface:
+            print(line, file=sys.stderr)
+    else:
+        print(f"halt: {halt.reason}", file=sys.stderr)
+    return 2
+
+
+__all__ = ["_emit", "_emit_halt"]

package/.agent-src/templates/scripts/work_engine/errors.py

@@ -0,0 +1,19 @@
+"""CLI-layer error type used by the dispatcher entry point.
+
+Lives in its own module so the helper modules (``state_io``,
+``input_builders``, etc.) can raise it without depending on
+``cli.py``, which would create an import cycle.
+
+Behaviour is identical to the original ``cli._CLIError`` it replaced
+in P2.3 of ``road-to-post-pr29-optimize.md`` — same name (private,
+underscore-prefixed) and same role: convert to exit code ``2`` at the
+``main()`` boundary.
+"""
+from __future__ import annotations
+
+
+class _CLIError(Exception):
+    """Raised on configuration or I/O problems. Converted to exit code 2."""
+
+
+__all__ = ["_CLIError"]

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -0,0 +1,76 @@
+"""Lifecycle-hook registry assembly for the CLI entry point.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Owns nothing but
+``_build_hook_registry`` and its chat-history helper. The function
+remains re-exported from ``work_engine.cli`` so the existing test
+import (``from work_engine.cli import _build_hook_registry``) and
+monkeypatch target (``work_engine.cli._build_hook_registry``) keep
+working without a breaking change.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .hooks import HookRegistry
+from .hooks.builtin import (
+    ChatHistoryAppendHook,
+    ChatHistoryHaltAppendHook,
+    ChatHistoryHeartbeatHook,
+    ChatHistoryTurnCheckHook,
+    DirectiveSetGuardHook,
+    HaltSurfaceAuditHook,
+    StateShapeValidationHook,
+    TraceHook,
+)
+from .hooks.settings import HookSettings, load_hook_settings
+
+
+def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
+    """Build the CLI-side :class:`HookRegistry` for one ``main()`` run.
+
+    Reads ``hooks.*`` from ``.agent-settings.yml`` and registers the
+    enabled hooks. The master switch ``hooks.enabled`` defaults to
+    ``False`` when the block (or the file) is missing — the registry
+    stays empty and golden replay flows are byte-stable.
+
+    ``--no-hooks`` on the CLI forces an empty registry regardless of
+    settings, which is the explicit escape hatch golden-replay test
+    harnesses can use.
+    """
+    registry = HookRegistry()
+    if getattr(args, "no_hooks", False):
+        return registry
+
+    settings_path = getattr(args, "hooks_config", None)
+    settings = load_hook_settings(settings_path)
+    if not settings.enabled:
+        return registry
+
+    if settings.trace:
+        TraceHook().register(registry)
+    if settings.halt_surface_audit:
+        HaltSurfaceAuditHook().register(registry)
+    if settings.state_shape_validation:
+        StateShapeValidationHook().register(registry)
+    if settings.directive_set_guard:
+        DirectiveSetGuardHook().register(registry)
+    if settings.chat_history_enabled:
+        _register_chat_history_hooks(registry, settings)
+
+    return registry
+
+
+def _register_chat_history_hooks(
+    registry: HookRegistry, settings: HookSettings,
+) -> None:
+    """Register the four chat-history hooks bound to the configured script."""
+    script = Path(settings.chat_history_script)
+    ChatHistoryTurnCheckHook(script).register(registry)
+    ChatHistoryAppendHook(script).register(registry)
+    ChatHistoryHaltAppendHook(script).register(registry)
+    ChatHistoryHeartbeatHook(script).register(registry)
+
+
+__all__ = ["_build_hook_registry", "_register_chat_history_hooks"]

package/.agent-src/templates/scripts/work_engine/input_builders.py

@@ -0,0 +1,163 @@
+"""File-based input builders and the load-or-build dispatch helper.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Owns the CLI's "first run" path:
+when no state file exists, build a fresh :class:`WorkState` from
+``--ticket-file``, ``--prompt-file``, ``--diff-file`` or
+``--file-file``. Every builder is byte-identical in behaviour to the
+pre-split version — the resolvers it calls and the persona / routing
+post-processing did not move.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .cli_args import _FMT_V0, _FMT_V1
+from .errors import _CLIError
+from .intent import populate_routing
+from .resolvers.diff import DiffResolverError, build_envelope as _build_diff_envelope
+from .resolvers.file import FileResolverError, build_envelope as _build_file_envelope
+from .resolvers.prompt import PromptResolverError, build_envelope as _build_prompt_envelope
+from .state import Input, WorkState
+from .state_io import _load, _maybe_raise_legacy_hint, _read_json
+
+
+def _load_or_build(
+    state_file: Path,
+    args: argparse.Namespace,
+) -> tuple[WorkState, str]:
+    """Return the WorkState to dispatch against plus its wire format.
+
+    Either loaded from ``state_file`` (format-preserving) or freshly
+    built from ``--ticket-file`` (R1), ``--prompt-file`` (R2),
+    ``--diff-file`` (R3) or ``--file-file`` (R3). Fresh ticket files
+    default to v0 wire format so that newly captured Goldens stay
+    byte-equal with the pre-Phase-4 baseline; the prompt / diff / file
+    paths emit v1 directly (v0 has no envelope concept for these
+    kinds). v1 round-trips for state files already on disk in v1 shape.
+    """
+    if state_file.exists():
+        return _load(state_file)
+    _maybe_raise_legacy_hint(state_file)
+    inputs = [
+        ("--ticket-file", args.ticket_file),
+        ("--prompt-file", args.prompt_file),
+        ("--diff-file", args.diff_file),
+        ("--file-file", args.file_file),
+    ]
+    supplied = [name for name, value in inputs if value is not None]
+    if len(supplied) > 1:
+        raise _CLIError(
+            f"{', '.join(supplied)} are mutually exclusive; pass exactly "
+            "one when building an initial state.",
+        )
+    if not supplied:
+        raise _CLIError(
+            f"No state file at {state_file} and no --ticket-file, "
+            "--prompt-file, --diff-file, or --file-file given; cannot "
+            "build an initial state.",
+        )
+    if args.prompt_file is not None:
+        return _build_from_prompt_file(args), _FMT_V1
+    if args.diff_file is not None:
+        return _build_from_diff_file(args), _FMT_V1
+    if args.file_file is not None:
+        return _build_from_file_file(args), _FMT_V1
+    ticket = _read_json(args.ticket_file)
+    if not isinstance(ticket, dict):
+        raise _CLIError(
+            f"--ticket-file must carry a JSON object; got {type(ticket).__name__}.",
+        )
+    work = WorkState(input=Input(kind="ticket", data=ticket))
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work, _FMT_V0
+
+
+def _build_from_prompt_file(args: argparse.Namespace) -> WorkState:
+    """Read ``--prompt-file`` as raw text and wrap it in a prompt envelope.
+
+    The file is read verbatim (UTF-8) and handed to the prompt resolver,
+    which validates non-emptiness and returns the canonical
+    ``Input(kind="prompt", data={raw, reconstructed_ac, assumptions})``
+    envelope. Persona is honoured the same way as the ticket path.
+    """
+    try:
+        raw = args.prompt_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {args.prompt_file}: {exc}") from exc
+    try:
+        envelope = _build_prompt_envelope(raw)
+    except PromptResolverError as exc:
+        raise _CLIError(f"--prompt-file is not a valid prompt: {exc}") from exc
+    work = WorkState(input=envelope)
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work
+
+
+def _build_from_diff_file(args: argparse.Namespace) -> WorkState:
+    """Read ``--diff-file`` as raw text and wrap it in a diff envelope.
+
+    The file is read verbatim (UTF-8) and handed to the diff resolver,
+    which validates the unified-diff header heuristic and returns the
+    canonical
+    ``Input(kind="diff", data={raw, reconstructed_ac, assumptions})``
+    envelope. ``populate_routing`` then routes the envelope to the
+    UI-improve directive set without running the prose classifier — see
+    :mod:`work_engine.intent.classify` for the routing contract.
+    """
+    try:
+        raw = args.diff_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {args.diff_file}: {exc}") from exc
+    try:
+        envelope = _build_diff_envelope(raw)
+    except DiffResolverError as exc:
+        raise _CLIError(f"--diff-file is not a valid diff: {exc}") from exc
+    work = WorkState(input=envelope)
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work
+
+
+def _build_from_file_file(args: argparse.Namespace) -> WorkState:
+    """Read ``--file-file`` as a single-line path and wrap it in a file envelope.
+
+    The file is read verbatim (UTF-8); the first non-empty line is taken
+    as the path reference and handed to the file resolver, which
+    validates path shape (non-empty, NUL-free, not a URL) and returns
+    the canonical
+    ``Input(kind="file", data={path, reconstructed_ac, assumptions})``
+    envelope. Trailing whitespace and additional lines are ignored —
+    the resolver treats the file's content as the path itself, not as
+    structured payload.
+    """
+    try:
+        raw = args.file_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {args.file_file}: {exc}") from exc
+    path = raw.strip().splitlines()[0] if raw.strip() else ""
+    try:
+        envelope = _build_file_envelope(path)
+    except FileResolverError as exc:
+        raise _CLIError(
+            f"--file-file does not carry a valid path: {exc}",
+        ) from exc
+    work = WorkState(input=envelope)
+    if args.persona:
+        work.persona = args.persona
+    populate_routing(work)
+    return work
+
+
+__all__ = [
+    "_build_from_diff_file",
+    "_build_from_file_file",
+    "_build_from_prompt_file",
+    "_load_or_build",
+]

package/.agent-src/templates/scripts/work_engine/migration/v0_to_v1.py

@@ -41,7 +41,39 @@ DEFAULT_V1_FILENAME = ".work-state.json"
 """Canonical filename for the v1 wire format."""
 
 BACKUP_SUFFIX = ".bak"
-"""Appended to the v0 source path when the migration archives it."""
+"""Appended to the v0 source path when the migration archives it.
+
+If the ``.bak`` slot is already taken (re-running the migration after
+an aborted run, manual rollback, etc.) the rotator falls back to
+``.bak.1``, ``.bak.2``, ... — see :func:`_rotate_backup_path`. The
+migration never silently overwrites an existing backup."""
+
+_MAX_BACKUP_ROTATIONS = 999
+"""Hard ceiling on rotated backup filenames; surfaces an explicit
+:class:`SchemaError` instead of looping forever if a checkout has
+hundreds of stale backups."""
+
+
+def _rotate_backup_path(source: Path) -> Path:
+    """Return the next free ``.bak`` slot for ``source``.
+
+    Tries ``source.bak`` first, then ``source.bak.1``,
+    ``source.bak.2``, ... up to :data:`_MAX_BACKUP_ROTATIONS`. The
+    rotator only inspects existence — collision-safe by construction —
+    and never deletes or overwrites prior backups.
+    """
+    primary = source.with_suffix(source.suffix + BACKUP_SUFFIX)
+    if not primary.exists():
+        return primary
+    for index in range(1, _MAX_BACKUP_ROTATIONS + 1):
+        candidate = primary.with_suffix(primary.suffix + f".{index}")
+        if not candidate.exists():
+            return candidate
+    raise SchemaError(
+        f"refusing to rotate backup for {source}: more than "
+        f"{_MAX_BACKUP_ROTATIONS} stale .bak files already exist; "
+        "clean them up before re-running the migration",
+    )
 
 
 def migrate_payload(payload: Any) -> dict[str, Any]:
@@ -143,7 +175,7 @@ def migrate_file(
     )
 
     if backup:
-        backup_path = source.with_suffix(source.suffix + BACKUP_SUFFIX)
+        backup_path = _rotate_backup_path(source)
         shutil.move(str(source), str(backup_path))
 
     return target

package/.agent-src/templates/scripts/work_engine/persona_policy.py

@@ -2,7 +2,7 @@
 
 Three personas ship today, each keyed by the string already carried
 on ``DeliveryState.persona`` (see
-``agents/contexts/implement-ticket-flow.md#personas``):
+``docs/contracts/implement-ticket-flow.md#personas``):
 
 ``senior-engineer``
     Default. Runs every step. No test widening.

package/.agent-src/templates/scripts/work_engine/resolvers/prompt.py

@@ -15,7 +15,7 @@ Why split the resolver from the refiner:
   it without touching the LLM-facing skill harness.
 - The refiner runs inside the dispatcher loop and is allowed to halt
   (medium-confidence assumptions report, low-confidence one-question
-  block) per :doc:`agents/contexts/implement-ticket-flow.md`. That
+  block) per :doc:`docs/contracts/implement-ticket-flow.md`. That
   control-flow surface does not belong in a resolver.
 
 Future R3 resolvers (``diff``, ``file``) follow the same pattern: thin

package/.agent-src/templates/scripts/work_engine/state_io.py

@@ -0,0 +1,202 @@
+"""State-file I/O helpers for the CLI entry point.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Holds the format-preserving
+load/save pair, the v0 legacy serialiser, the JSON reader, the
+``DeliveryState`` projection helpers, and the legacy-file migration
+hint. Behaviour is byte-identical to the pre-split version — Goldens
+stay green.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from . import state as _state_module
+from .cli_args import DEFAULT_STATE_FILE, LEGACY_STATE_FILE, _FMT_V0, _FMT_V1
+from .delivery_state import DeliveryState
+from .errors import _CLIError
+from .migration.v0_to_v1 import migrate_payload
+from .state import SchemaError, WorkState
+
+
+def _maybe_raise_legacy_hint(state_file: Path) -> None:
+    """Surface a migration hint when only the pre-1.15.0 file is present.
+
+    The dispatcher renamed the default state file from
+    ``.implement-ticket-state.json`` to ``.work-state.json`` in 1.15.0
+    (alongside the ``implement_ticket → work_engine`` package move).
+    Existing checkouts that still carry the legacy file would otherwise
+    fail with a generic "no state file" message. This helper detects
+    the legacy file in the same directory and points the user at the
+    one-shot migration command instead.
+
+    Only fires when ``state_file`` has the canonical default name and
+    sits next to a legacy file — explicit ``--state-file`` overrides
+    bypass the hint so power users can carry their own naming scheme.
+    """
+    if state_file.name != DEFAULT_STATE_FILE.name:
+        return
+    legacy_candidate = state_file.with_name(LEGACY_STATE_FILE.name)
+    if not legacy_candidate.is_file():
+        return
+    raise _CLIError(
+        f"Found legacy state file {legacy_candidate} but no "
+        f"{state_file}. The default state file was renamed in 1.15.0. "
+        f"Run `python3 -m work_engine.migration.v0_to_v1 "
+        f"{legacy_candidate}` to migrate, or pass `--state-file "
+        f"{legacy_candidate}` to keep using the old name. See "
+        "docs/MIGRATION.md.",
+    )
+
+
+def _load(state_file: Path) -> tuple[WorkState, str]:
+    """Load ``state_file`` and tag it with the wire format detected."""
+    data = _read_json(state_file)
+    if not isinstance(data, dict):
+        raise _CLIError(
+            f"State file {state_file} must carry a JSON object; "
+            f"got {type(data).__name__}.",
+        )
+
+    # v1 declares ``version``; v0 has none. Anything else is invalid.
+    if data.get("version") == _state_module.SCHEMA_VERSION:
+        try:
+            return _state_module.from_dict(data), _FMT_V1
+        except SchemaError as exc:
+            raise _CLIError(f"State file shape is invalid: {exc}") from exc
+    if "version" in data:
+        raise _CLIError(
+            f"State file shape is invalid: unsupported version "
+            f"{data.get('version')!r}; expected {_state_module.SCHEMA_VERSION}",
+        )
+    if "ticket" not in data:
+        raise _CLIError(
+            "State file shape is invalid: missing 'ticket' (v0) or "
+            "'version' (v1) — file is neither shape.",
+        )
+    try:
+        migrated = migrate_payload(data)
+        return _state_module.from_dict(migrated), _FMT_V0
+    except SchemaError as exc:
+        raise _CLIError(f"State file shape is invalid: {exc}") from exc
+
+
+def _to_delivery(work: WorkState) -> DeliveryState:
+    """Project ``work`` into a ``DeliveryState`` for handler dispatch.
+
+    R1 P4 S1 (Option A2): handlers continue to consume ``DeliveryState``
+    with ``state.ticket``; the ``WorkState`` wrapper exists at the CLI
+    boundary so the dispatcher's directive-set selection has a v1
+    state object to read ``directive_set`` from. Mutable containers
+    (``memory``, ``changes``, ``outcomes``, ``questions``) are passed
+    by reference — in-place mutations land on both objects without an
+    explicit sync. Reassignments (``state.plan = …``, ``state.report
+    = …``) are mirrored back by :func:`_sync_back`.
+    """
+    return DeliveryState(
+        ticket=work.input.data,
+        persona=work.persona,
+        memory=work.memory,
+        plan=work.plan,
+        changes=work.changes,
+        tests=work.tests,
+        verify=work.verify,
+        outcomes=work.outcomes,
+        questions=work.questions,
+        report=work.report,
+        ui_audit=work.ui_audit,
+        ui_design=work.ui_design,
+        ui_review=work.ui_review,
+        ui_polish=work.ui_polish,
+        contract=work.contract,
+        stitch=work.stitch,
+        stack=work.stack,
+    )
+
+
+def _sync_back(work: WorkState, delivery: DeliveryState) -> None:
+    """Mirror handler mutations from ``delivery`` back into ``work``.
+
+    Container fields are shared by reference (see :func:`_to_delivery`)
+    so the assignment is a no-op for those — we still mirror them
+    defensively to cover the case where a handler reassigned the
+    attribute (``state.memory = [new_list]``) instead of mutating in
+    place.
+    """
+    work.input.data = delivery.ticket
+    work.persona = delivery.persona
+    work.memory = delivery.memory
+    work.plan = delivery.plan
+    work.changes = delivery.changes
+    work.tests = delivery.tests
+    work.verify = delivery.verify
+    work.outcomes = delivery.outcomes
+    work.questions = delivery.questions
+    work.report = delivery.report
+    work.ui_audit = delivery.ui_audit
+    work.ui_design = delivery.ui_design
+    work.ui_review = delivery.ui_review
+    work.ui_polish = delivery.ui_polish
+    work.contract = delivery.contract
+    work.stitch = delivery.stitch
+    work.stack = delivery.stack
+
+
+def _save(state_file: Path, work: WorkState, fmt: str) -> None:
+    """Persist ``work`` in the wire format it was loaded with.
+
+    v1 emits the canonical envelope via :func:`work_engine.state.to_dict`;
+    v0 emits the legacy flat shape that ``DeliveryState.asdict`` used
+    to produce, byte-identical to the pre-Phase-4 output so the
+    Golden Transcript replay stays green.
+    """
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    payload = _state_module.to_dict(work) if fmt == _FMT_V1 else _to_v0_dict(work)
+    state_file.write_text(
+        json.dumps(payload, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _to_v0_dict(work: WorkState) -> dict[str, Any]:
+    """Serialise ``work`` in the legacy v0 wire format.
+
+    Field order matches ``DeliveryState`` declaration order so
+    pre-Phase-4 state files round-trip byte-equal.
+    """
+    return {
+        "ticket": work.input.data,
+        "persona": work.persona,
+        "memory": work.memory,
+        "plan": work.plan,
+        "changes": work.changes,
+        "tests": work.tests,
+        "verify": work.verify,
+        "outcomes": work.outcomes,
+        "questions": work.questions,
+        "report": work.report,
+    }
+
+
+def _read_json(path: Path):
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise _CLIError(f"Cannot read {path}: {exc}") from exc
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise _CLIError(f"Invalid JSON in {path}: {exc}") from exc
+
+
+__all__ = [
+    "_load",
+    "_maybe_raise_legacy_hint",
+    "_read_json",
+    "_save",
+    "_sync_back",
+    "_to_delivery",
+    "_to_v0_dict",
+]