@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/templates/scripts/telemetry_status.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""``./agent-config telemetry:status`` — read-only status report.
+
+Prints the current ``telemetry.artifact_engagement`` configuration
+plus log statistics. Safe even when telemetry is disabled — never
+creates the log, never validates, never writes. ``--format json`` is
+the machine-readable contract.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from telemetry.engagement import EngagementSchemaError, parse_event
+from telemetry.settings import TelemetrySettings, read_settings
+
+
+def _last_event_ts(log_path: Path) -> str | None:
+    """Return the ``ts`` of the last well-formed event, or None.
+
+    Reads from the tail to keep the cost bounded on long logs. We
+    skip malformed lines silently — Phase 4 surfaces those via the
+    aggregator's ``--strict`` flag.
+    """
+    if not log_path.is_file():
+        return None
+    try:
+        with log_path.open("rb") as fh:
+            fh.seek(0, 2)  # EOF
+            size = fh.tell()
+            chunk_size = min(size, 4096)
+            fh.seek(size - chunk_size)
+            tail = fh.read().decode("utf-8", errors="replace")
+    except OSError:
+        return None
+    for line in reversed(tail.splitlines()):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            event = parse_event(line + "\n")
+        except EngagementSchemaError:
+            continue
+        return event.ts
+    return None
+
+
+def _log_stats(log_path: Path) -> dict[str, Any]:
+    if not log_path.is_file():
+        return {"exists": False, "size_bytes": 0, "line_count": 0}
+    try:
+        size = log_path.stat().st_size
+        with log_path.open("rb") as fh:
+            line_count = sum(1 for _ in fh)
+    except OSError as exc:
+        return {"exists": True, "error": str(exc)}
+    return {"exists": True, "size_bytes": size, "line_count": line_count}
+
+
+def _build_report(settings: TelemetrySettings) -> dict[str, Any]:
+    log_path = settings.log_path
+    return {
+        "enabled": settings.enabled,
+        "section_present": settings.section_present,
+        "granularity": settings.granularity,
+        "record": {
+            "consulted": settings.record_consulted,
+            "applied": settings.record_applied,
+        },
+        "log": {
+            "path": str(log_path),
+            **_log_stats(log_path),
+            "last_event_ts": _last_event_ts(log_path),
+        },
+    }
+
+
+def _render_text(report: dict[str, Any]) -> str:
+    lines: list[str] = []
+    enabled = "✅  enabled" if report["enabled"] else "⛔  disabled"
+    if not report["section_present"]:
+        enabled += " (no telemetry section in .agent-settings.yml — using defaults)"
+    lines.append(f"  artifact-engagement: {enabled}")
+    lines.append(f"  granularity:         {report['granularity']}")
+    rec = report["record"]
+    lines.append(
+        f"  record:              consulted={rec['consulted']} "
+        f"applied={rec['applied']}"
+    )
+    log = report["log"]
+    lines.append(f"  log path:            {log['path']}")
+    if log.get("exists"):
+        if "error" in log:
+            lines.append(f"  log error:           {log['error']}")
+        else:
+            lines.append(
+                f"  log size:            {log['size_bytes']} bytes "
+                f"({log['line_count']} events)"
+            )
+            if log.get("last_event_ts"):
+                lines.append(f"  last event ts:       {log['last_event_ts']}")
+    else:
+        lines.append("  log:                 not yet created")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="agent-config telemetry:status",
+        description=(
+            "Print the artifact-engagement telemetry status. Read-only "
+            "— never creates the log, never modifies settings."
+        ),
+    )
+    parser.add_argument("--format", choices=("text", "json"), default="text")
+    parser.add_argument(
+        "--settings",
+        type=Path,
+        default=Path(".agent-settings.yml"),
+        help="Override settings path (tests).",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        settings = read_settings(args.settings)
+    except OSError as exc:
+        print(f"❌  cannot read settings: {exc}", file=sys.stderr)
+        return 2
+
+    report = _build_report(settings)
+    if args.format == "json":
+        print(json.dumps(report, sort_keys=True, indent=2))
+    else:
+        print(_render_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,58 @@
+"""``work_engine`` — universal execution engine (R1).
+
+The package owns the linear step dispatcher that drives
+``/implement-ticket`` and any future intent-routed flow. Phase 2 added
+the persistent ``state`` schema and the v0→v1 migration; Phase 3 moves
+the dispatcher, CLI and step modules over from the legacy
+``implement_ticket`` package — which is now a thin compatibility shim
+that re-exports from here with a ``DeprecationWarning``.
+
+Architectural constraints (from
+``docs/contracts/adr-implement-ticket-runtime.md`` and
+``docs/contracts/implement-ticket-flow.md``):
+
+- Runtime is Python 3.10+.
+- The dispatcher is linear, not a DAG. Eight fixed steps, fixed order.
+- ``DeliveryState`` is the only object shared between steps — no
+  hidden state, no side channels.
+- Every step terminates in ``success | blocked | partial``. ``blocked``
+  and ``partial`` halt the flow and surface numbered questions.
+- The dispatcher never calls git, writes commits, or opens PRs.
+"""
+from __future__ import annotations
+
+from .delivery_state import (
+    AGENT_DIRECTIVE_PREFIX,
+    DeliveryState,
+    Outcome,
+    Step,
+    StepResult,
+    agent_directive,
+    is_agent_directive,
+)
+from .cli import DEFAULT_STATE_FILE, main
+from .dispatcher import STEP_ORDER, dispatch
+from .persona_policy import (
+    DEFAULT_PERSONA,
+    PersonaPolicy,
+    known_personas,
+    resolve_policy,
+)
+
+__all__ = [
+    "AGENT_DIRECTIVE_PREFIX",
+    "DEFAULT_PERSONA",
+    "DEFAULT_STATE_FILE",
+    "DeliveryState",
+    "Outcome",
+    "PersonaPolicy",
+    "STEP_ORDER",
+    "Step",
+    "StepResult",
+    "agent_directive",
+    "dispatch",
+    "is_agent_directive",
+    "known_personas",
+    "main",
+    "resolve_policy",
+]

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

@@ -0,0 +1,9 @@
+"""Module entry point — lets ``python3 -m implement_ticket`` run the CLI."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,195 @@
+"""Command-line entry point for ``/implement-ticket``.
+
+Minimal Option-A transport: the script loads a persisted state file,
+runs the dispatcher once, writes the updated state back, and prints
+either the delivery report (on SUCCESS) or the halt surface —
+directive plus numbered questions — on BLOCKED/PARTIAL.
+
+The script never edits code, runs tests, or opens pull requests.
+All of that is delegated to the agent via ``@agent-directive:``
+markers per
+``docs/contracts/implement-ticket-flow.md#agent-directives``. The
+agent executes the directive, writes the resulting slice back to
+the state file, and re-invokes this script to resume.
+
+Wire format (R1 P4 S1, Option A2): the CLI accepts both the legacy
+v0 wire format (``{"ticket": …, "persona": …}``) and the v1 schema
+(``{"version": 1, "input": {"kind": "ticket", "data": …}}``). Loaded
+state is wrapped in :class:`work_engine.state.WorkState` for the
+boundary; before dispatch it is projected into a ``DeliveryState``
+the step handlers understand. After dispatch the mutations are
+mirrored back, and the file is rewritten in the **same** wire format
+it was loaded with — Goldens captured against v0 stay v0 byte-for-
+byte, while flows that already store v1 round-trip as v1.
+
+Layout (post P2.3 of ``road-to-post-pr29-optimize.md``): this file
+is a thin orchestrator. The argument parser, state I/O, file-input
+builders, hook bootstrap, and stdout/stderr emitters live in their
+own leaf modules under ``work_engine`` — see ``cli_args``,
+``state_io``, ``input_builders``, ``hook_bootstrap``, ``emitters``,
+``errors``. Public names (``main``, ``DEFAULT_STATE_FILE``) and the
+private monkeypatch surface (``_build_hook_registry``,
+``_CLIError``, ``_load_or_build``, …) are re-exported here so
+existing imports and patch targets continue to resolve.
+
+Exit codes:
+
+- ``0`` — flow reached SUCCESS; ``state.report`` printed.
+- ``1`` — flow halted BLOCKED; halt surface printed on stdout, the
+  state file carries the updated ``outcomes`` and ``questions`` so
+  the agent can resume.
+- ``2`` — argument or I/O error (ticket file missing, JSON parse
+  failure, etc.). The state file is *not* written in this case.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from .cli_args import (
+    DEFAULT_STATE_FILE,
+    LEGACY_STATE_FILE,
+    _build_parser,
+    _FMT_V0,
+    _FMT_V1,
+)
+from .delivery_state import Outcome
+from .dispatcher import (
+    assert_kind_supported,
+    dispatch,
+    load_directive_set,
+    select_directive_set,
+)
+from .emitters import _emit, _emit_halt
+from .errors import _CLIError
+from .hook_bootstrap import _build_hook_registry, _register_chat_history_hooks
+from .hooks import HookContext, HookEvent, HookRunner
+from .input_builders import (
+    _build_from_diff_file,
+    _build_from_file_file,
+    _build_from_prompt_file,
+    _load_or_build,
+)
+from .state_io import (
+    _load,
+    _maybe_raise_legacy_hint,
+    _read_json,
+    _save,
+    _sync_back,
+    _to_delivery,
+    _to_v0_dict,
+)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run one dispatch cycle against the persisted state.
+
+    ``argv`` is taken as-is; pass ``None`` to fall back to
+    ``sys.argv[1:]`` (the usual entry-point contract).
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    state_file: Path = args.state_file
+
+    runner = HookRunner(_build_hook_registry(args))
+
+    halt = runner.emit(
+        HookEvent.BEFORE_LOAD,
+        HookContext(state_file=state_file, args=args),
+    )
+    if halt is not None:
+        return _emit_halt(halt)
+
+    try:
+        work, fmt = _load_or_build(state_file, args)
+    except _CLIError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    halt = runner.emit(
+        HookEvent.AFTER_LOAD,
+        HookContext(state_file=state_file, work=work, fmt=fmt, args=args),
+    )
+    if halt is not None:
+        return _emit_halt(halt)
+
+    try:
+        set_name = select_directive_set(work)
+        assert_kind_supported(work.input.kind, set_name)
+        steps = load_directive_set(set_name)
+    except (ValueError, NotImplementedError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    delivery = _to_delivery(work)
+
+    halt = runner.emit(
+        HookEvent.BEFORE_DISPATCH,
+        HookContext(work=work, delivery=delivery, set_name=set_name, args=args),
+    )
+    if halt is not None:
+        return _emit_halt(halt)
+
+    final, halting = dispatch(delivery, steps, hooks=runner)
+
+    halt = runner.emit(
+        HookEvent.AFTER_DISPATCH,
+        HookContext(
+            work=work,
+            delivery=delivery,
+            final=final,
+            halting=halting,
+            args=args,
+        ),
+    )
+    if halt is not None:
+        return _emit_halt(halt)
+
+    _sync_back(work, delivery)
+
+    halt = runner.emit(
+        HookEvent.BEFORE_SAVE,
+        HookContext(work=work, delivery=delivery, fmt=fmt, args=args),
+    )
+    if halt is not None:
+        return _emit_halt(halt)
+
+    _save(state_file, work, fmt)
+
+    halt = runner.emit(
+        HookEvent.AFTER_SAVE,
+        HookContext(work=work, state_file=state_file, fmt=fmt, args=args),
+    )
+    if halt is not None:
+        # State is already on disk; exit 2 still per the P3 branch table.
+        return _emit_halt(halt)
+
+    _emit(work, final, halting)
+    return 0 if final is Outcome.SUCCESS else 1
+
+
+__all__ = [
+    "DEFAULT_STATE_FILE",
+    "LEGACY_STATE_FILE",
+    "_CLIError",
+    "_FMT_V0",
+    "_FMT_V1",
+    "_build_from_diff_file",
+    "_build_from_file_file",
+    "_build_from_prompt_file",
+    "_build_hook_registry",
+    "_build_parser",
+    "_emit",
+    "_emit_halt",
+    "_load",
+    "_load_or_build",
+    "_maybe_raise_legacy_hint",
+    "_read_json",
+    "_register_chat_history_hooks",
+    "_save",
+    "_sync_back",
+    "_to_delivery",
+    "_to_v0_dict",
+    "main",
+]

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

@@ -0,0 +1,116 @@
+"""Argument parser and state-file constants for the CLI entry point.
+
+Extracted from ``cli.py`` in P2.3 of
+``road-to-post-pr29-optimize.md``. Behaviour-preserving: the parser
+shape, default values, help strings and exit-code semantics are
+byte-identical to the pre-split version. The constants moved here
+so the parser default and the legacy-file detector both reference
+a single source of truth.
+"""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+DEFAULT_STATE_FILE = Path(".work-state.json")
+"""State file used when ``--state-file`` is not passed.
+
+Renamed from ``.implement-ticket-state.json`` in 1.15.0 alongside the
+``implement_ticket → work_engine`` package move. The legacy filename is
+still recognised on load (see :data:`LEGACY_STATE_FILE` below) so that
+existing checkouts surface a clear migration message instead of a
+silent "no state file" error."""
+
+LEGACY_STATE_FILE = Path(".implement-ticket-state.json")
+"""Pre-1.15.0 default state file. Detected only as a migration hint;
+never written to. See ``docs/MIGRATION.md``."""
+
+_FMT_V0 = "v0"
+_FMT_V1 = "v1"
+"""Wire-format markers carried alongside the loaded :class:`WorkState`.
+
+Format-preserving roundtrip: ``_load`` records which shape it parsed,
+``_save`` rewrites in that same shape. v0 in → v0 out (Goldens stay
+byte-equal); v1 in → v1 out (future flows produced by the migration
+tool or a fresh v1 init keep their envelope fields)."""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="implement-ticket",
+        description="Run one dispatch cycle of the /implement-ticket flow.",
+    )
+    parser.add_argument(
+        "--state-file",
+        type=Path,
+        default=DEFAULT_STATE_FILE,
+        help=f"Path to persisted state JSON (default: {DEFAULT_STATE_FILE}).",
+    )
+    parser.add_argument(
+        "--ticket-file",
+        type=Path,
+        default=None,
+        help="JSON file carrying the ticket payload; used only when the "
+        "state file does not exist yet.",
+    )
+    parser.add_argument(
+        "--prompt-file",
+        type=Path,
+        default=None,
+        help="Plain-text file carrying the raw user prompt; builds an "
+        "input.kind='prompt' envelope. Mutually exclusive with "
+        "--ticket-file. Used only when the state file does not exist yet.",
+    )
+    parser.add_argument(
+        "--diff-file",
+        type=Path,
+        default=None,
+        help="Plain-text file carrying a unified diff payload; builds an "
+        "input.kind='diff' envelope routed through the UI-improve "
+        "directive set. Mutually exclusive with --ticket-file / "
+        "--prompt-file / --file-file. Used only when the state file does "
+        "not exist yet.",
+    )
+    parser.add_argument(
+        "--file-file",
+        type=Path,
+        default=None,
+        help="Plain-text file carrying a single path reference (one line); "
+        "builds an input.kind='file' envelope routed through the UI-improve "
+        "directive set. Mutually exclusive with --ticket-file / "
+        "--prompt-file / --diff-file. Used only when the state file does "
+        "not exist yet.",
+    )
+    parser.add_argument(
+        "--persona",
+        type=str,
+        default=None,
+        help="Persona name (senior-engineer | qa | advisory). Only honoured "
+        "when the state file does not exist yet; ignored on resume so a "
+        "mid-flight persona switch cannot silently change behaviour.",
+    )
+    parser.add_argument(
+        "--no-hooks",
+        action="store_true",
+        default=False,
+        help="Disable every lifecycle hook for this run. Use in golden-"
+        "replay test harnesses so a future settings change cannot "
+        "silently invalidate captured outputs.",
+    )
+    parser.add_argument(
+        "--hooks-config",
+        type=Path,
+        default=None,
+        help="Override the path to the agent-settings file used to resolve "
+        "the hooks.* block. Defaults to ./.agent-settings.yml.",
+    )
+    return parser
+
+
+__all__ = [
+    "DEFAULT_STATE_FILE",
+    "LEGACY_STATE_FILE",
+    "_FMT_V0",
+    "_FMT_V1",
+    "_build_parser",
+]

package/.agent-src/templates/scripts/{implement_ticket → 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.
@@ -75,6 +75,13 @@ class DeliveryState:
     outcomes: dict[str, str] = field(default_factory=dict)
     questions: list[str] = field(default_factory=list)
     report: str = ""
+    ui_audit: dict[str, Any] | None = None
+    ui_design: dict[str, Any] | None = None
+    ui_review: dict[str, Any] | None = None
+    ui_polish: dict[str, Any] | None = None
+    contract: dict[str, Any] | None = None
+    stitch: dict[str, Any] | None = None
+    stack: dict[str, Any] | None = None
 
 
 Step = Callable[[DeliveryState], StepResult]
@@ -96,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/__init__.py

@@ -0,0 +1,33 @@
+"""Directive-set bundles consumed by the dispatcher.
+
+A *directive set* is a coherent group of step handlers (refine,
+memory, analyze, plan, implement, test, verify, report) tuned for a
+particular kind of work — backend coding, UI work, mixed front+back
+work, and so on. The dispatcher selects exactly one set per cycle
+(see ``dispatcher.select_directive_set``) and walks its eight steps
+in the canonical order.
+
+Each set is a Python sub-package exposing a single function::
+
+    def get_steps() -> Mapping[str, Step]:
+        '''Return the {step_name: handler} mapping the dispatcher walks.'''
+
+The mapping must cover every entry in :data:`dispatcher.STEP_ORDER`;
+incomplete bundles raise ``KeyError`` at dispatch time.
+
+Roadmap status (R1 Phase 4):
+
+- ``backend`` — fully implemented; landing in Step 3 of this phase.
+- ``ui`` — stub; lands in Roadmap 3 (``road-to-product-ui-track.md``).
+- ``ui_trivial`` — stub; lands in Roadmap 3 V2.
+- ``mixed`` — stub; lands in Roadmap 3.
+
+The schema (``state.KNOWN_DIRECTIVE_SETS``) carries the *external*
+names ``ui``, ``ui-trivial``, ``mixed``; the directory layout uses
+underscores (``ui_trivial``) because Python packages cannot contain
+hyphens. The dispatcher's loader is the single place that translates
+between the two.
+"""
+from __future__ import annotations
+
+__all__: list[str] = []

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

@@ -0,0 +1,98 @@
+"""Backend directive set — step handlers for the backend-coding flow.
+
+Each module exposes a single ``run`` callable that matches the
+``Step`` protocol defined in ``...delivery_state``. The dispatcher
+wires them into the ``STEP_ORDER`` mapping at call time; nothing in
+this package imports handlers eagerly, so a partial wiring during
+development is caught by the dispatcher's missing-step check rather
+than by an import-time failure.
+
+This is the first concrete entry in the
+:mod:`work_engine.directives` package. R1 Phase 4 Step 3 moved the
+handlers here from the original ``work_engine.steps`` location so
+the upcoming generalized dispatcher (Step 2) can select between
+multiple directive sets uniformly via :func:`get_steps`. The
+external behavior — flow order, ambiguity surfaces, halt-points —
+is unchanged.
+
+The deterministic gates (``refine``, ``memory``, ``analyze``)
+validate upstream state; the delegation gates (``plan``,
+``implement``, ``test``, ``verify``) halt with
+``@agent-directive:`` markers so the orchestrator can invoke the
+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 ``docs/contracts/implement-ticket-flow.md`` for the
+slice contracts each handler writes to.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ...delivery_state import Step
+from . import analyze, implement, memory, plan, refine, report, test, verify
+
+DIRECTIVE_SET_NAME = "backend"
+"""External name carried in ``state.directive_set`` for this set."""
+
+SUPPORTED_KINDS: tuple[str, ...] = ("ticket", "prompt")
+"""Input kinds this directive set knows how to handle.
+
+Read by :func:`work_engine.dispatcher.assert_kind_supported` before the
+loop starts. The schema's :data:`work_engine.state.KNOWN_INPUT_KINDS` is
+the *envelope* whitelist (what is accepted on disk); ``SUPPORTED_KINDS``
+is the *capability* whitelist (what this set can actually drive end to
+end).
+
+R1 only carried ``ticket``. R2 Phase 3 Step 3 added ``prompt`` once the
+``refine`` step learned to detect prompt envelopes (presence of ``raw``
+key in ``state.ticket``), delegate to the ``refine-prompt`` skill on
+the first pass, and route the resulting confidence band into
+``SUCCESS`` / ``PARTIAL`` / ``BLOCKED`` per
+``agents/roadmaps/archive/road-to-prompt-driven-execution.md`` Phase 3."""
+
+_STEPS = (refine, memory, analyze, plan, implement, test, verify, report)
+
+
+def all_ambiguities() -> dict[str, tuple[dict[str, str], ...]]:
+    """Return `{step_name: AMBIGUITIES}` for every step in flow order.
+
+    Used by documentation generators and the ``test_ambiguity_coverage``
+    suite to prove every step explicitly declares what can surface a
+    ``BLOCKED`` outcome. Steps that always succeed (``memory``,
+    ``report``) return an empty tuple — declared intent, not an
+    omission.
+    """
+    return {step.__name__.rsplit(".", 1)[-1]: step.AMBIGUITIES for step in _STEPS}
+
+
+def get_steps() -> Mapping[str, Step]:
+    """Return the ``{step_name: handler}`` mapping the dispatcher walks.
+
+    Each value is the module-level ``run`` callable matching the
+    :data:`work_engine.delivery_state.Step` protocol —
+    ``Callable[[DeliveryState], StepResult]`` — exactly what
+    :func:`work_engine.dispatcher.dispatch` calls. Order of insertion
+    matches the canonical backend flow (refine → memory → analyze →
+    plan → implement → test → verify → report); the dispatcher's own
+    ``STEP_ORDER`` is the single source of truth for *which* steps
+    exist, but the directive set is the single source of truth for
+    *how* each one runs.
+    """
+    return {step.__name__.rsplit(".", 1)[-1]: step.run for step in _STEPS}
+
+
+__all__ = [
+    "DIRECTIVE_SET_NAME",
+    "SUPPORTED_KINDS",
+    "all_ambiguities",
+    "analyze",
+    "get_steps",
+    "implement",
+    "memory",
+    "plan",
+    "refine",
+    "report",
+    "test",
+    "verify",
+]