@event4u/agent-config 6.1.0 → 7.0.0

package/dist/agent-src/templates/scripts/work_engine/_lib/user_global_paths.py

@@ -1,249 +0,0 @@
-"""Vendor-namespaced user-global path resolution.
-
-Phase 1 of road-to-event4u-namespace-and-claude-desktop.md. Single source
-of truth for "where does this package keep user-global state on disk?".
-Replaces hard-coded ``~/.config/agent-config/`` literals scattered across
-``scripts/_lib`` and ``scripts/ai_council``.
-
-Resolution order:
-
-  1. ``$EVENT4U_CONFIG_HOME``  — full path override (testing + power users).
-  2. ``~/.event4u/agent-config/``  — vendor-namespaced source-of-truth.
-
-For backward compatibility during the transition, ``legacy_xdg_root()``
-exposes the old ``~/.config/agent-config/`` path so loaders can read
-state written by pre-2.4 installs. Writers should never target the
-legacy path; the auto-migration shim (Phase 3) copies state once into
-the new namespace.
-
-Contract — pure, read-only, never auto-creates directories.
-"""
-from __future__ import annotations
-
-import os
-import shutil
-from pathlib import Path
-from typing import Optional
-
-#: Marker suffix for in-progress entry copies during migration. A copy
-#: that crashes mid-flight leaves ``<name><suffix><pid>`` behind so the
-#: next run can clean it up before retrying — instead of treating a
-#: partial subdir as a completed copy.
-_PARTIAL_SUFFIX = ".event4u-partial-"
-
-#: Environment variable that overrides ``event4u_root()`` outright.
-#: Accepts a full path (``~`` expanded). Primarily used by tests; power
-#: users may also point this at a custom location.
-EVENT4U_HOME_ENV = "EVENT4U_CONFIG_HOME"
-
-#: Vendor-namespaced default. Relative to the user's home directory.
-DEFAULT_EVENT4U_ROOT_RELATIVE = Path(".event4u") / "agent-config"
-
-#: Legacy XDG-shaped default written by pre-2.4 installs. Read-only
-#: fallback during the transition; never the target of a write.
-LEGACY_XDG_ROOT_RELATIVE = Path(".config") / "agent-config"
-
-
-def event4u_root(env: Optional[dict] = None) -> Path:
-    """Return the active user-global root directory.
-
-    Honours ``EVENT4U_CONFIG_HOME`` first, falls back to
-    ``~/.event4u/agent-config/``. Never creates the directory.
-    """
-    env_map = env if env is not None else os.environ
-    override = env_map.get(EVENT4U_HOME_ENV)
-    if override:
-        return Path(override).expanduser()
-    return Path.home() / DEFAULT_EVENT4U_ROOT_RELATIVE
-
-
-def legacy_xdg_root() -> Path:
-    """Return the pre-2.4 user-global root at ``~/.config/agent-config/``.
-
-    Used by loaders during the transition to read settings, lockfiles,
-    and keys written before the namespace migration ran. Writers MUST
-    NOT target this path — only ``event4u_root()`` is a valid write
-    target. Never creates the directory.
-    """
-    return Path.home() / LEGACY_XDG_ROOT_RELATIVE
-
-
-def resolve_with_fallback(
-    relative_name: str,
-    *,
-    env: Optional[dict] = None,
-) -> Optional[Path]:
-    """Resolve a named file/dir under the user-global root, with legacy fallback.
-
-    Returns the new-namespace path if it exists on disk, otherwise the
-    legacy XDG path if it exists, otherwise ``None``. Callers that need
-    the *write target* (regardless of existence) should use
-    ``event4u_root() / relative_name`` directly.
-
-    ``relative_name`` is a forward-slash separated string (e.g.
-    ``"installed.lock"`` or ``"agents/global"``). It is treated as a
-    path fragment relative to the chosen root; absolute paths are
-    rejected with ``ValueError``.
-    """
-    fragment = Path(relative_name)
-    if fragment.is_absolute():
-        raise ValueError(
-            f"resolve_with_fallback expects a relative path, got {relative_name!r}"
-        )
-    new_path = event4u_root(env=env) / fragment
-    if new_path.exists():
-        return new_path
-    legacy_path = legacy_xdg_root() / fragment
-    if legacy_path.exists():
-        return legacy_path
-    return None
-
-
-def write_target(relative_name: str, *, env: Optional[dict] = None) -> Path:
-    """Return the canonical write target for a named user-global file/dir.
-
-    Always rooted at ``event4u_root()`` — writers never target the
-    legacy XDG path. Caller is responsible for ``mkdir(parents=True)``
-    on the parent before writing. Never creates the directory itself.
-    """
-    fragment = Path(relative_name)
-    if fragment.is_absolute():
-        raise ValueError(
-            f"write_target expects a relative path, got {relative_name!r}"
-        )
-    return event4u_root(env=env) / fragment
-
-
-#: Breadcrumb dropped into the legacy root after a successful migration.
-#: Tells the user where their state now lives and how to clean up. The
-#: legacy tree itself is never auto-deleted — only the user does that.
-MIGRATION_BREADCRUMB_NAME = "MIGRATED.md"
-
-_BREADCRUMB_TEMPLATE = """# Migrated to `~/.event4u/agent-config/`
-
-This directory (`~/.config/agent-config/`) is the **legacy** location
-for `event4u/agent-config` user-global state. As of v2.4 the canonical
-location is `~/.event4u/agent-config/`.
-
-The migration shim has already copied your settings, keys, lockfiles,
-and overrides into the new namespace. File modes (0600 on keys) were
-preserved. Loaders prefer the new path but still read from this tree
-as a fallback, so removing it is safe **once you've confirmed** the
-new location is working.
-
-## To clean up
-
-```bash
-rm -rf ~/.config/agent-config
-```
-
-## Why the move
-
-`~/.config/` is a generic XDG-shaped directory shared by many tools.
-`~/.event4u/agent-config/` is vendor-namespaced and avoids collisions
-with unrelated CLIs. See
-`agents/roadmaps/road-to-event4u-namespace-and-claude-desktop.md` for
-the full rationale.
-"""
-
-
-def migrate_legacy_namespace(
-    *,
-    env: Optional[dict] = None,
-    legacy_root_override: Optional[Path] = None,
-) -> bool:
-    """Copy pre-2.4 user-global state from legacy XDG root into the new namespace.
-
-    Idempotent and safe to call on every install / init. Returns ``True``
-    if a copy ran during this invocation, ``False`` when the migration
-    was already complete or there was nothing to migrate.
-
-    Contract:
-
-    - Never auto-deletes the legacy tree — that's the user's call (the
-      breadcrumb at ``~/.config/agent-config/MIGRATED.md`` documents it).
-    - Preserves file modes via ``shutil.copytree(..., copy_function=copy2)``
-      so 0600 key files stay 0600 after the copy.
-    - If the new root already exists with any content, the migration
-      treats it as already-done and only writes the breadcrumb (if
-      missing) — never overwrites new-namespace state.
-    - If the legacy root is missing or empty, the function is a no-op.
-    - Per-entry atomic write: each entry is copied to a sibling
-      ``<name>.event4u-partial-<pid>`` and then ``os.replace``'d into
-      the final name. If a previous run crashed mid-``copytree``, the
-      leftover ``*.event4u-partial-*`` siblings are cleaned up at the
-      top of the next run before retrying — a partial directory is
-      never mistaken for a completed copy.
-
-    ``legacy_root_override`` is for tests; production callers leave it ``None``.
-    """
-    legacy_root = (
-        legacy_root_override if legacy_root_override is not None else legacy_xdg_root()
-    )
-    new_root = event4u_root(env=env)
-
-    if not legacy_root.exists() or not legacy_root.is_dir():
-        return False
-
-    # Skip the migrated-breadcrumb itself when checking for content so a
-    # second invocation does not loop on its own marker.
-    legacy_entries = [
-        p for p in legacy_root.iterdir() if p.name != MIGRATION_BREADCRUMB_NAME
-    ]
-    if not legacy_entries:
-        return False
-
-    # Real content check ignores partial-copy debris from a prior
-    # interrupted run; otherwise the breadcrumb would be written for
-    # a half-finished migration and retry would never run.
-    new_has_content = new_root.exists() and any(
-        not _is_partial_entry(p) for p in new_root.iterdir()
-    )
-    if new_has_content:
-        _ensure_breadcrumb(legacy_root)
-        return False
-
-    new_root.mkdir(parents=True, exist_ok=True)
-    _purge_partial_entries(new_root)
-
-    for entry in legacy_entries:
-        target = new_root / entry.name
-        if target.exists():
-            continue
-        staging = new_root / f"{entry.name}{_PARTIAL_SUFFIX}{os.getpid()}"
-        if staging.exists():
-            _remove_path(staging)
-        if entry.is_dir():
-            shutil.copytree(entry, staging, copy_function=shutil.copy2)
-        else:
-            shutil.copy2(entry, staging)
-        os.replace(staging, target)
-
-    _ensure_breadcrumb(legacy_root)
-    return True
-
-
-def _is_partial_entry(path: Path) -> bool:
-    return _PARTIAL_SUFFIX in path.name
-
-
-def _purge_partial_entries(new_root: Path) -> None:
-    """Remove ``*.event4u-partial-*`` leftovers from a previous interrupted run."""
-    for entry in new_root.iterdir():
-        if _is_partial_entry(entry):
-            _remove_path(entry)
-
-
-def _remove_path(path: Path) -> None:
-    if path.is_dir() and not path.is_symlink():
-        shutil.rmtree(path)
-    else:
-        path.unlink(missing_ok=True)
-
-
-def _ensure_breadcrumb(legacy_root: Path) -> None:
-    """Write the ``MIGRATED.md`` breadcrumb into ``legacy_root`` if absent."""
-    breadcrumb = legacy_root / MIGRATION_BREADCRUMB_NAME
-    if breadcrumb.exists():
-        return
-    breadcrumb.write_text(_BREADCRUMB_TEMPLATE, encoding="utf-8")

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

@@ -1,195 +0,0 @@
-"""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, state_file=state_file, event="BEFORE_LOAD")
-
-    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, work=work, state_file=state_file, event="AFTER_LOAD")
-
-    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, work=work, state_file=state_file, event="BEFORE_DISPATCH")
-
-    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, work=work, state_file=state_file, event="AFTER_DISPATCH")
-
-    _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, work=work, state_file=state_file, event="BEFORE_SAVE")
-
-    _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, work=work, state_file=state_file, event="AFTER_SAVE")
-
-    _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/dist/agent-src/templates/scripts/work_engine/cli_args.py

@@ -1,116 +0,0 @@
-"""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/dist/agent-src/templates/scripts/work_engine/delivery_state.py

@@ -1,137 +0,0 @@
-"""``DeliveryState`` — the only object shared between orchestrator steps.
-
-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.
-
-Steps return a ``StepResult`` with one of three ``Outcome`` values:
-
-- ``SUCCESS``  — step populated its slice of ``DeliveryState`` and the
-  dispatcher continues to the next step.
-- ``BLOCKED``  — step hit an ambiguity it cannot resolve on its own.
-  ``questions`` carries pre-formatted numbered options per the
-  ``user-interaction`` rule. The dispatcher halts.
-- ``PARTIAL``  — step populated its slice *and* produced open
-  questions. The dispatcher halts with the same surface as BLOCKED;
-  the calling orchestrator (Phase 3) decides whether to prompt the
-  user to continue or stop.
-
-``DeliveryState`` is a plain dataclass rather than a typed dict so
-step handlers can rely on attribute access, defaults, and mutation
-semantics without resorting to dictionary indirection.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any, Callable
-
-
-class Outcome(str, Enum):
-    """Terminal outcome of a single step.
-
-    Subclassing ``str`` keeps JSON serialisation trivial (Outcome
-    values round-trip as their string form) without hand-rolling a
-    ``__str__`` override.
-    """
-
-    SUCCESS = "success"
-    BLOCKED = "blocked"
-    PARTIAL = "partial"
-
-
-@dataclass
-class StepResult:
-    """Return value of a single ``Step`` invocation.
-
-    ``questions`` is only populated for ``BLOCKED`` / ``PARTIAL``
-    outcomes. Each entry is a fully-formatted numbered line so the
-    dispatcher can surface them verbatim without reformatting.
-    """
-
-    outcome: Outcome
-    questions: list[str] = field(default_factory=list)
-    message: str = ""
-
-
-@dataclass
-class DeliveryState:
-    """Canonical state passed between orchestrator steps.
-
-    Field order matches the table in
-    ``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.
-    """
-
-    ticket: dict[str, Any]
-    persona: str = "senior-engineer"
-    memory: list[dict[str, Any]] = field(default_factory=list)
-    plan: Any = None
-    changes: list[dict[str, Any]] = field(default_factory=list)
-    tests: Any = None
-    verify: Any = None
-    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]
-"""Protocol every step handler must satisfy.
-
-A step reads and writes ``DeliveryState`` in place; its return value
-carries only the terminal ``Outcome`` and any surfaced questions.
-"""
-
-
-AGENT_DIRECTIVE_PREFIX = "@agent-directive:"
-"""Marker that flags a ``questions[0]`` entry as agent-addressed, not user-addressed.
-
-When a step cannot run deterministically from pure Python (edits,
-subprocess calls, anything that needs tools the dispatcher doesn't
-own), it returns ``BLOCKED`` with this prefix as the first entry of
-``questions``. The orchestrator reads it and drives the matching
-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
-``docs/contracts/implement-ticket-flow.md#agent-directives``.
-"""
-
-
-def agent_directive(name: str, **payload: Any) -> str:
-    """Format a canonical ``@agent-directive:`` line.
-
-    ``name`` is the directive verb the agent dispatches on (for
-    example ``"implement-plan"`` or ``"run-tests"``). ``payload``
-    entries are rendered as ``key=value`` pairs on the same line, so
-    the whole directive stays a single greppable string. Values are
-    coerced with ``str`` — richer payloads belong on the
-    ``DeliveryState`` itself, not in the directive line.
-    """
-    suffix = " ".join(f"{key}={value}" for key, value in payload.items())
-    return (
-        f"{AGENT_DIRECTIVE_PREFIX} {name} {suffix}".strip()
-        if suffix
-        else f"{AGENT_DIRECTIVE_PREFIX} {name}"
-    )
-
-
-def is_agent_directive(question: str) -> bool:
-    """True when ``question`` is an agent-addressed directive line.
-
-    Used by the orchestrator to split ``state.questions`` into the
-    agent-facing directive (at most one, always at index 0) and the
-    user-facing numbered options (everything else).
-    """
-    return isinstance(question, str) and question.lstrip().startswith(
-        AGENT_DIRECTIVE_PREFIX,
-    )