@event4u/agent-config 1.13.0 → 1.14.0

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -0,0 +1,141 @@
+"""Read ``hooks.*`` from ``.agent-settings.yml`` into :class:`HookSettings`.
+
+Mirror of the chat-history settings pattern (``scripts/command_suggester/
+settings.py``):
+
+* Lazy PyYAML import — the engine works without yaml installed when no
+  settings file is present (test fixtures, cloud bundles).
+* Default-permissive: a missing file or missing ``hooks:`` block returns
+  :class:`HookSettings` with ``enabled=False`` — every hook off, every
+  golden replay safe by construction.
+* Malformed YAML / unreadable file → defaults; the engine degrades
+  silently rather than crashing the CLI.
+* Chat-history hooks gate on **two** switches: ``hooks.chat_history.
+  enabled`` AND the global ``chat_history.enabled``. Either off → no
+  chat-history hook registers.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
+DEFAULT_CHAT_HISTORY_SCRIPT = "scripts/chat_history.py"
+
+
+@dataclass(frozen=True)
+class HookSettings:
+    """Resolved view of the ``hooks:`` block.
+
+    ``enabled`` is the master switch. When ``False`` the registry stays
+    empty regardless of the per-hook fields; this is the default when no
+    settings file exists or no ``hooks`` block is declared, and it is
+    what keeps golden-replay tests byte-stable.
+    """
+
+    enabled: bool = False
+    trace: bool = False
+    halt_surface_audit: bool = False
+    state_shape_validation: bool = False
+    directive_set_guard: bool = False
+    chat_history_enabled: bool = False
+    chat_history_script: str = DEFAULT_CHAT_HISTORY_SCRIPT
+
+
+_DEFAULT = HookSettings()
+
+
+def load_hook_settings(
+    settings_path: Path | str | None = None,
+) -> HookSettings:
+    """Return :class:`HookSettings` hydrated from ``.agent-settings.yml``.
+
+    ``settings_path`` defaults to ``./.agent-settings.yml`` relative to
+    the current working directory — same convention as chat-history.
+    """
+    path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
+    raw = _read_yaml(path)
+    if raw is None:
+        return _DEFAULT
+    return _settings_from_raw(raw)
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    return data
+
+
+def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
+    hooks = data.get("hooks")
+    if not isinstance(hooks, dict):
+        return _DEFAULT
+    enabled = _coerce_bool(hooks.get("enabled"), False)
+    if not enabled:
+        return HookSettings(enabled=False)
+
+    chat_section = hooks.get("chat_history")
+    if isinstance(chat_section, dict):
+        chat_block_enabled = _coerce_bool(chat_section.get("enabled"), True)
+        chat_script = str(
+            chat_section.get("script") or DEFAULT_CHAT_HISTORY_SCRIPT
+        )
+    else:
+        chat_block_enabled = True
+        chat_script = DEFAULT_CHAT_HISTORY_SCRIPT
+
+    global_chat = data.get("chat_history")
+    global_chat_on = (
+        isinstance(global_chat, dict)
+        and _coerce_bool(global_chat.get("enabled"), False)
+    )
+
+    return HookSettings(
+        enabled=True,
+        trace=_coerce_bool(hooks.get("trace"), False),
+        halt_surface_audit=_coerce_bool(
+            hooks.get("halt_surface_audit"), True
+        ),
+        state_shape_validation=_coerce_bool(
+            hooks.get("state_shape_validation"), True
+        ),
+        directive_set_guard=_coerce_bool(
+            hooks.get("directive_set_guard"), True
+        ),
+        chat_history_enabled=chat_block_enabled and global_chat_on,
+        chat_history_script=chat_script,
+    )
+
+
+def _coerce_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    if isinstance(value, str):
+        s = value.strip().lower()
+        if s in ("true", "yes", "on", "1"):
+            return True
+        if s in ("false", "no", "off", "0"):
+            return False
+    return default
+
+
+__all__ = [
+    "DEFAULT_CHAT_HISTORY_SCRIPT",
+    "DEFAULT_SETTINGS_FILE",
+    "HookSettings",
+    "load_hook_settings",
+]

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

@@ -0,0 +1,47 @@
+"""Intent classification for the universal engine (R3 Phase 1 Step 2).
+
+The :mod:`work_engine.intent.classify` module turns a raw user prompt
+(or a ticket's title + body) into one of the five labels the dispatcher
+routes against:
+
+- ``ui-build`` — new screen, page, or component.
+- ``ui-improve`` — change to an existing screen / component.
+- ``ui-trivial`` — single-file, single-concern micro-edit (color, copy,
+  one class, one prop). Hard preconditions are enforced again at apply
+  time; the classifier only labels the *intent*, not the safety floor.
+- ``mixed`` — both UI and backend signals; routes to the mixed track.
+- ``backend-coding`` — default; no UI signal.
+
+The classifier is intentionally heuristic-only — it consumes nothing
+beyond the prompt text and optional ticket title. Confidence-band
+gating, AC reconstruction, and assumption surfacing all stay in
+``directives/backend/refine.py`` (R2). This module only owns the
+*label*; the dispatcher owns the routing.
+"""
+from __future__ import annotations
+
+from . import classify
+from .classify import (
+    INTENT_BACKEND,
+    INTENT_MIXED,
+    INTENT_UI_BUILD,
+    INTENT_UI_IMPROVE,
+    INTENT_UI_TRIVIAL,
+    KNOWN_INTENTS,
+    classify_intent,
+    directive_set_for,
+    populate_routing,
+)
+
+__all__ = [
+    "INTENT_BACKEND",
+    "INTENT_MIXED",
+    "INTENT_UI_BUILD",
+    "INTENT_UI_IMPROVE",
+    "INTENT_UI_TRIVIAL",
+    "KNOWN_INTENTS",
+    "classify",
+    "classify_intent",
+    "directive_set_for",
+    "populate_routing",
+]

package/.agent-src/templates/scripts/work_engine/intent/classify.py

@@ -0,0 +1,280 @@
+"""Heuristic intent classifier — see :mod:`work_engine.intent` for context.
+
+The classifier walks a small priority ladder against the lower-cased
+prompt + optional ticket title. First match wins; ``backend-coding`` is
+the fall-through default so every prompt always lands on a known label.
+
+Priority order (deliberately fixed):
+
+1. **Trivial-UI** — UI signal AND a trivial-edit verb pattern (``change
+   color``, ``make … red``, ``rename label``, ``fix copy``) AND no
+   structural verb (``add``, ``build``, ``create``, ``introduce``).
+2. **Mixed** — UI signal AND a backend signal (``endpoint``, ``API``,
+   ``migration``, ``schema``, ``query``, ``job``, ``queue``).
+3. **UI-Improve** — UI signal AND an improve/redesign/refactor verb,
+   OR explicit "existing" surface markers.
+4. **UI-Build** — UI signal AND a build/create/add verb, OR new-screen
+   markers (``new page``, ``new screen``, ``new component``).
+5. **Backend-Coding** — default.
+
+The label is the dispatcher's *only* input for routing. Confidence
+band, ``ui_intent`` flag from the scorer, and AC reconstruction stay
+the resolution surface — the classifier does not look at them.
+"""
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..state import WorkState
+
+INTENT_UI_BUILD = "ui-build"
+INTENT_UI_IMPROVE = "ui-improve"
+INTENT_UI_TRIVIAL = "ui-trivial"
+INTENT_MIXED = "mixed"
+INTENT_BACKEND = "backend-coding"
+
+KNOWN_INTENTS: frozenset[str] = frozenset(
+    {
+        INTENT_UI_BUILD,
+        INTENT_UI_IMPROVE,
+        INTENT_UI_TRIVIAL,
+        INTENT_MIXED,
+        INTENT_BACKEND,
+    },
+)
+"""All labels the classifier can return.
+
+Locked here so the dispatcher's mapping table and the test suite share
+one source of truth."""
+
+_UI_NOUNS: frozenset[str] = frozenset(
+    {
+        "ui", "screen", "page", "view", "form", "modal", "dialog",
+        "button", "card", "tile",
+        "header", "footer", "nav", "navigation", "sidebar", "menu",
+        "dropdown", "tab", "panel", "layout", "component", "icon",
+        "tooltip", "toast", "banner", "badge", "avatar", "label",
+        "checkbox", "radio", "toggle", "switch", "stepper", "wizard",
+    },
+)
+"""Strong UI nouns — exclusive UI meaning.
+
+Deliberately omits ``table``, ``list``, ``input``, and ``field``:
+``table``/``list`` collide with database tables and Python/PHP lists;
+``input``/``field`` collide with function inputs, command inputs, and
+JSON/DB fields. Genuine UI prompts that mean form inputs always come
+with a strong-UI noun nearby (``form``, ``page``, ``component``)."""
+
+_UI_STYLE: frozenset[str] = frozenset(
+    {
+        "color", "colour", "css", "tailwind", "padding", "margin",
+        "spacing", "font", "typography", "responsive", "mobile",
+        "dark mode", "light mode", "theme", "shadow", "border",
+        "rounded", "radius",
+    },
+)
+
+_BACKEND_SIGNALS: frozenset[str] = frozenset(
+    {
+        "endpoint", "api", "route", "controller", "service",
+        "migration", "schema", "table", "column", "index", "query",
+        "queue", "job", "worker", "webhook", "policy", "gate",
+        "command", "cron", "broadcast", "event", "listener",
+    },
+)
+
+_TRIVIAL_VERBS: frozenset[str] = frozenset(
+    {
+        "rename", "relabel", "tweak", "adjust", "swap", "change",
+    },
+)
+
+_IMPROVE_VERBS: frozenset[str] = frozenset(
+    {
+        "improve", "polish", "redesign", "rework", "refine",
+        "refactor", "tighten", "clean", "fix", "update", "tune",
+    },
+)
+
+_BUILD_VERBS: frozenset[str] = frozenset(
+    {
+        "add", "build", "create", "introduce", "implement", "ship",
+        "draft", "scaffold", "wire",
+    },
+)
+
+_NEW_SURFACE: re.Pattern[str] = re.compile(
+    r"\b(new|fresh|blank)\s+(page|screen|view|component|form|modal|tile|dashboard)\b",
+)
+
+_EXISTING_SURFACE: re.Pattern[str] = re.compile(
+    r"\b(existing|current|the)\s+(page|screen|view|component|form|modal)\b",
+)
+
+_TRIVIAL_PATTERN: re.Pattern[str] = re.compile(
+    r"\b(make|change|update|set|swap)\b[^.]{0,40}\b("
+    r"red|blue|green|yellow|black|white|primary|secondary"
+    r"|color|colour|copy|text|label|wording|class|prop)\b",
+)
+
+
+def classify_intent(raw: str, *, title: str | None = None) -> str:
+    """Return one of :data:`KNOWN_INTENTS` for the supplied text.
+
+    Parameters
+    ----------
+    raw:
+        The user prompt or ticket body. Whitespace is normalised
+        internally; ``""`` and ``None`` resolve to ``backend-coding``.
+    title:
+        Optional ticket title. Concatenated with ``raw`` before
+        scanning so single-line ticket headlines (`"Add CSV export"`)
+        produce the same label whether they arrive in the body or the
+        title slot.
+    """
+    text = " ".join(filter(None, (title, raw))).strip().lower()
+    if not text:
+        return INTENT_BACKEND
+
+    has_ui = _has_ui_signal(text)
+    has_backend = _has_backend_signal(text)
+
+    if has_ui and _is_trivial(text):
+        return INTENT_UI_TRIVIAL
+    if has_ui and has_backend:
+        return INTENT_MIXED
+    if has_ui and _is_improve(text):
+        return INTENT_UI_IMPROVE
+    if has_ui and _is_build(text):
+        return INTENT_UI_BUILD
+    if has_ui:
+        # UI signal but no clear verb — default to ui-improve so the
+        # full audit gate engages. ui-build would skip the existing-
+        # surface check, which is the wrong default when the prompt
+        # is ambiguous.
+        return INTENT_UI_IMPROVE
+    return INTENT_BACKEND
+
+
+def directive_set_for(intent: str) -> str:
+    """Map an intent label to a directive-set name.
+
+    Centralised here so the dispatcher and the refine step share one
+    routing table; a future intent (``infra``, ``security-review``)
+    only needs a single edit. Unknown labels raise ``ValueError`` —
+    silently falling back to ``backend`` would mask classifier bugs.
+    """
+    if intent not in KNOWN_INTENTS:
+        raise ValueError(
+            f"unknown intent {intent!r}; "
+            f"expected one of {sorted(KNOWN_INTENTS)}",
+        )
+    if intent in (INTENT_UI_BUILD, INTENT_UI_IMPROVE):
+        return "ui"
+    if intent == INTENT_UI_TRIVIAL:
+        return "ui-trivial"
+    if intent == INTENT_MIXED:
+        return "mixed"
+    return "backend"
+
+
+# --- helpers ----------------------------------------------------------
+
+def _has_ui_signal(text: str) -> bool:
+    if any(re.search(rf"\b{re.escape(w)}\b", text) for w in _UI_NOUNS):
+        return True
+    return any(s in text for s in _UI_STYLE)
+
+
+def _has_backend_signal(text: str) -> bool:
+    return any(re.search(rf"\b{re.escape(w)}\b", text) for w in _BACKEND_SIGNALS)
+
+
+def _is_trivial(text: str) -> bool:
+    if _TRIVIAL_PATTERN.search(text):
+        return True
+    return any(re.search(rf"\b{re.escape(v)}\b", text) for v in _TRIVIAL_VERBS) and len(
+        text.split()
+    ) <= 14
+
+
+def _is_improve(text: str) -> bool:
+    if _EXISTING_SURFACE.search(text):
+        return True
+    return any(re.search(rf"\b{re.escape(v)}\b", text) for v in _IMPROVE_VERBS)
+
+
+def _is_build(text: str) -> bool:
+    if _NEW_SURFACE.search(text):
+        return True
+    return any(re.search(rf"\b{re.escape(v)}\b", text) for v in _BUILD_VERBS)
+
+
+def populate_routing(state: "WorkState") -> None:
+    """Classify ``state.input`` and write ``intent`` + ``directive_set`` in place.
+
+    Idempotent and override-safe: if ``state.intent`` is already a
+    UI-track or mixed label (``ui-build``, ``ui-improve``, ``ui-trivial``,
+    ``mixed``), the routing is left untouched. Only freshly-built states
+    carrying the construction default ``backend-coding`` are reclassified.
+    Loaded state files round-trip without losing a previously-recorded
+    intent — including a manual user override in the JSON.
+
+    The text fed to the classifier depends on the input envelope:
+
+    - ``prompt`` → ``state.input.data["raw"]``
+    - ``ticket`` → ``state.input.data["title"]`` + first non-empty
+      acceptance criterion, falling back to ``description`` when AC is
+      missing. Title is passed separately so single-line ticket
+      headlines (``"Add CSV export"``) classify identically whether
+      they arrive in the body or the title slot.
+    - ``diff`` / ``file`` → routed directly to ``ui-improve`` without
+      running the heuristic. Both envelopes are R3 Phase 1 inputs that
+      describe an existing UI surface ("improve this screen"); the
+      classifier's prose-oriented signals do not apply, and the audit +
+      design directives downstream are the right place to read the
+      diff/file contents.
+    """
+    if state.intent != INTENT_BACKEND:
+        return
+
+    if state.input.kind in {"diff", "file"}:
+        state.intent = INTENT_UI_IMPROVE
+        state.directive_set = directive_set_for(INTENT_UI_IMPROVE)
+        return
+
+    text, title = _extract_text(state)
+    intent = classify_intent(text, title=title)
+    state.intent = intent
+    state.directive_set = directive_set_for(intent)
+
+
+def _extract_text(state: "WorkState") -> tuple[str, str | None]:
+    data = state.input.data or {}
+    if state.input.kind == "prompt":
+        return str(data.get("raw") or ""), None
+    title = data.get("title")
+    title_str = str(title) if isinstance(title, str) and title.strip() else None
+    body_parts: list[str] = []
+    ac = data.get("acceptance_criteria")
+    if isinstance(ac, list):
+        body_parts.extend(str(item) for item in ac if isinstance(item, str))
+    description = data.get("description")
+    if isinstance(description, str) and description.strip():
+        body_parts.append(description)
+    return " ".join(body_parts), title_str
+
+
+__all__ = [
+    "INTENT_BACKEND",
+    "INTENT_MIXED",
+    "INTENT_UI_BUILD",
+    "INTENT_UI_IMPROVE",
+    "INTENT_UI_TRIVIAL",
+    "KNOWN_INTENTS",
+    "classify_intent",
+    "directive_set_for",
+    "populate_routing",
+]

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

@@ -0,0 +1,8 @@
+"""State-file migrations for the universal engine.
+
+Each module in this package owns one direction of one schema bump. The
+historical bumps must remain runnable so a freshly-cloned repository
+that finds a v0 state file from a long-running branch can catch up
+without manual intervention.
+"""
+from __future__ import annotations

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

@@ -0,0 +1,199 @@
+"""Migrate a v0 ``DeliveryState`` JSON file to the v1 schema.
+
+The v0 era used ``.implement-ticket-state.json`` and stored the ticket
+under a flat ``ticket`` key. v1 wraps the payload under ``input.kind``
+/ ``input.data`` and adds ``intent``, ``directive_set``, and
+``version``. The default destination is ``.work-state.json`` next to
+the v0 file; the v0 file is renamed to ``.implement-ticket-state.json.bak``
+to preserve the rollback surface.
+
+The module is both importable and runnable:
+
+    python3 -m work_engine.migration.v0_to_v1 .implement-ticket-state.json
+
+Idempotency: ``migrate_payload`` accepts a payload that already looks
+like v1 and returns it unchanged. ``migrate_file`` refuses to migrate
+twice — if the destination already exists it raises rather than
+silently overwriting work.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any, Sequence
+
+from ..state import (
+    DEFAULT_DIRECTIVE_SET,
+    DEFAULT_INTENT,
+    SCHEMA_VERSION,
+    SchemaError,
+)
+
+DEFAULT_V0_FILENAME = ".implement-ticket-state.json"
+"""Path the dispatcher used while the engine still lived under
+``implement_ticket``. The migration looks here when no source path is
+passed on the CLI."""
+
+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."""
+
+
+def migrate_payload(payload: Any) -> dict[str, Any]:
+    """Return the v1 form of ``payload``.
+
+    A payload that already declares ``version: 1`` is returned
+    unchanged (deep-copied via ``json.loads(json.dumps(...))`` so the
+    caller cannot accidentally mutate the input). Anything else is
+    treated as v0 and wrapped: ``ticket`` becomes ``input.data``,
+    ``input.kind`` is set to ``"ticket"``, and the engine defaults are
+    filled in.
+
+    Raises
+    ------
+    SchemaError
+        If the payload is not a dict, declares a higher version than
+        this migration knows about, or lacks a ``ticket`` key.
+    """
+    if not isinstance(payload, dict):
+        raise SchemaError(
+            f"v0 state must be a JSON object; got {type(payload).__name__}",
+        )
+
+    declared_version = payload.get("version")
+    if declared_version == SCHEMA_VERSION:
+        return json.loads(json.dumps(payload))
+    if declared_version is not None:
+        raise SchemaError(
+            f"cannot migrate from version {declared_version!r} to "
+            f"{SCHEMA_VERSION}; this script only handles v0 (no version key)",
+        )
+
+    if "ticket" not in payload:
+        raise SchemaError(
+            "v0 state must carry a 'ticket' key; got keys: "
+            f"{sorted(payload.keys())}",
+        )
+    ticket = payload["ticket"]
+    if not isinstance(ticket, dict):
+        raise SchemaError(
+            f"v0 state.ticket must be a JSON object; got {type(ticket).__name__}",
+        )
+
+    return {
+        "version": SCHEMA_VERSION,
+        "input": {"kind": "ticket", "data": ticket},
+        "intent": DEFAULT_INTENT,
+        "directive_set": DEFAULT_DIRECTIVE_SET,
+        "persona": payload.get("persona", "senior-engineer"),
+        "memory": list(payload.get("memory", [])),
+        "plan": payload.get("plan"),
+        "changes": list(payload.get("changes", [])),
+        "tests": payload.get("tests"),
+        "verify": payload.get("verify"),
+        "outcomes": dict(payload.get("outcomes", {})),
+        "questions": list(payload.get("questions", [])),
+        "report": payload.get("report", ""),
+    }
+
+
+def migrate_file(
+    source: Path,
+    *,
+    destination: Path | None = None,
+    backup: bool = True,
+) -> Path:
+    """Migrate the v0 state file at ``source`` and write the v1 result.
+
+    ``destination`` defaults to :data:`DEFAULT_V1_FILENAME` next to
+    ``source``. When ``backup`` is true (the default) the original
+    file is renamed with :data:`BACKUP_SUFFIX` appended; when false,
+    the original is left untouched. The destination must not exist —
+    refusing to overwrite is the safety net against accidental
+    double-migration on CI.
+
+    Returns the destination path on success.
+    """
+    if not source.is_file():
+        raise SchemaError(f"v0 state file not found: {source}")
+
+    raw = source.read_text(encoding="utf-8")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise SchemaError(f"invalid JSON in {source}: {exc}") from exc
+
+    target = destination or source.with_name(DEFAULT_V1_FILENAME)
+    if target.exists():
+        raise SchemaError(
+            f"refusing to overwrite existing destination {target}; "
+            "delete or rename it first",
+        )
+
+    migrated = migrate_payload(payload)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        json.dumps(migrated, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+
+    if backup:
+        backup_path = source.with_suffix(source.suffix + BACKUP_SUFFIX)
+        shutil.move(str(source), str(backup_path))
+
+    return target
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point — ``python3 -m work_engine.migration.v0_to_v1``.
+
+    Exits ``0`` on success, ``2`` on any :class:`SchemaError` so the
+    invoking shell can branch on the failure category.
+    """
+    parser = argparse.ArgumentParser(
+        prog="work_engine.migration.v0_to_v1",
+        description="Migrate a legacy .implement-ticket-state.json file to "
+        "the v1 .work-state.json schema.",
+    )
+    parser.add_argument(
+        "source",
+        type=Path,
+        nargs="?",
+        default=Path(DEFAULT_V0_FILENAME),
+        help=f"Path to the v0 state file (default: {DEFAULT_V0_FILENAME}).",
+    )
+    parser.add_argument(
+        "--destination",
+        type=Path,
+        default=None,
+        help="Path to write the v1 file to "
+        f"(default: {DEFAULT_V1_FILENAME} next to source).",
+    )
+    parser.add_argument(
+        "--no-backup",
+        action="store_true",
+        help="Do not rename the v0 source to .bak after migration.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        target = migrate_file(
+            args.source,
+            destination=args.destination,
+            backup=not args.no_backup,
+        )
+    except SchemaError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    print(f"migrated {args.source} → {target}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,22 @@
+"""Input resolvers — turn raw user-supplied payloads into envelopes.
+
+A resolver wraps a typed source (a free-form prompt, a diff, a file
+reference) into the canonical :class:`work_engine.state.Input` shape so
+the dispatcher only ever speaks one schema. The R1 ticket flow does not
+need a resolver — ticket payloads arrive pre-structured from
+``/implement-ticket``; R2 introduces :mod:`.prompt`; R3 Phase 1 adds
+:mod:`.diff` and :mod:`.file` for the UI-improve track ("improve this
+screen via diff/PR" and "improve this existing component/page").
+
+Resolvers are deliberately thin: they normalize, they do not interpret.
+Reconstruction of acceptance criteria + assumptions + confidence is the
+job of the ``refine-prompt`` skill (R2 Phase 3) called from the
+``refine`` step, not the resolver. Keeping the split sharp means the
+envelope shape stays cheap to round-trip through state and the heavy
+lifting stays with the agent-directive halt where it belongs.
+"""
+from __future__ import annotations
+
+from . import diff, file, prompt
+
+__all__ = ["diff", "file", "prompt"]