@event4u/agent-config 1.13.0 → 1.15.0

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,231 @@
+"""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.
+
+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]:
+    """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 = _rotate_backup_path(source)
+        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/{implement_ticket → 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/__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"]

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

@@ -0,0 +1,106 @@
+"""Diff resolver — wrap a unified-diff payload as an :class:`Input` envelope.
+
+The resolver is the R3 Phase 1 entry point for the "improve this screen via
+diff/PR" surface: a user (or `/work` adapter) hands the engine a patch text,
+the resolver normalises it, and the dispatcher routes it through the UI-track
+``ui-improve`` directive set.
+
+Like :mod:`work_engine.resolvers.prompt`, this module is intentionally thin:
+it normalises and rejects garbage payloads, nothing more. Reconstruction of
+acceptance criteria + assumptions + confidence is the job of the
+``refine-prompt`` skill (R2 Phase 3) running against the diff once the engine
+hits the ``refine`` step. 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.
+
+The envelope mirrors the prompt resolver's shape so a single refiner code
+path can read both — ``{raw, reconstructed_ac, assumptions}``. The only
+material difference is the heuristic header check that rejects payloads
+that obviously are not unified-diff text.
+"""
+from __future__ import annotations
+
+import re
+
+from ..state import Input
+
+KIND = "diff"
+"""Wire value carried in :attr:`work_engine.state.Input.kind`."""
+
+_MIN_DIFF_LEN = 1
+"""Minimum non-whitespace character count before the heuristic runs.
+
+The resolver is not a *quality* gate; it only rejects literally empty payloads
+and obvious non-diffs. A semantically empty diff (e.g., headers but no hunks)
+is still accepted so the refiner can score its tractability and surface a
+``low``-band halt where appropriate."""
+
+_DIFF_MARKERS = (
+    re.compile(r"^diff --git ", re.MULTILINE),
+    re.compile(r"^--- ", re.MULTILINE),
+    re.compile(r"^\+\+\+ ", re.MULTILINE),
+    re.compile(r"^@@ ", re.MULTILINE),
+    re.compile(r"^Index: ", re.MULTILINE),
+)
+"""Heuristic markers that flag a payload as a unified or git-style diff.
+
+A payload qualifies if **any** marker matches — the resolver accepts unified
+diffs (``--- ``/``+++ ``/``@@ ``), ``git diff`` output (``diff --git``), and
+the legacy ``Index: `` SVN/CVS header. The match is anchored at line start so
+quoted snippets inside prose ("the function `--- foo` failed") do not pass
+the gate."""
+
+
+class DiffResolverError(ValueError):
+    """Raised when a payload cannot be resolved into a diff envelope."""
+
+
+def build_envelope(raw: str) -> Input:
+    """Return an :class:`Input` carrying the raw diff + empty refinement slots.
+
+    Parameters
+    ----------
+    raw:
+        The user-supplied diff text. Whitespace is preserved verbatim — the
+        refiner reads original spacing/casing when scoring goal clarity, and
+        a unified-diff round-trip cannot tolerate normalised whitespace.
+
+    Returns
+    -------
+    Input
+        Envelope of shape
+        ``{"kind": "diff", "data": {"raw": <raw>, "reconstructed_ac": [],
+        "assumptions": []}}``. The two empty lists are placeholders the
+        ``refine-prompt`` skill writes into on the rebound from ``refine``.
+
+    Raises
+    ------
+    DiffResolverError
+        If ``raw`` is not a string, contains no non-whitespace characters,
+        or does not match any :data:`_DIFF_MARKERS`. The marker check guards
+        against accidentally routing free-form prose through the diff path.
+    """
+    if not isinstance(raw, str):
+        raise DiffResolverError(
+            f"diff must be a string; got {type(raw).__name__}",
+        )
+    if len(raw.strip()) < _MIN_DIFF_LEN:
+        raise DiffResolverError(
+            "diff is empty or whitespace-only — nothing to resolve",
+        )
+    if not any(marker.search(raw) for marker in _DIFF_MARKERS):
+        raise DiffResolverError(
+            "payload does not look like a unified diff — expected one of "
+            "'diff --git', '--- ', '+++ ', '@@ ', or 'Index: ' headers",
+        )
+    return Input(
+        kind=KIND,
+        data={
+            "raw": raw,
+            "reconstructed_ac": [],
+            "assumptions": [],
+        },
+    )
+
+
+__all__ = ["KIND", "DiffResolverError", "build_envelope"]