@event4u/agent-config 6.1.0 → 7.0.1

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

@@ -1,33 +0,0 @@
-"""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/dist/agent-src/templates/scripts/work_engine/directives/backend/__init__.py

@@ -1,98 +0,0 @@
-"""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",
-]

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

@@ -1,98 +0,0 @@
-"""``analyze`` step — deterministic precondition gate.
-
-The step runs no analysis of its own: the real impact analysis is
-owned by the agent between the ``memory`` and ``plan`` steps. The
-gate's job is to confirm the upstream slices are populated enough
-for planning to be meaningful.
-
-Checks, in order:
-
-1. ``refine`` outcome must be ``success`` — the ticket is refined.
-2. ``memory`` outcome must be ``success`` — priors were queried
-   (an empty result set is still a successful query, per the
-   ``memory`` step's own contract).
-3. The ticket must still carry acceptance criteria — guards against
-   a resuming caller overwriting ``state.ticket`` between runs.
-
-On any missing precondition the step returns ``BLOCKED`` with the
-reason spelled out and numbered options per the ``user-interaction``
-rule. Otherwise it returns ``SUCCESS`` without mutating state.
-"""
-from __future__ import annotations
-
-from ...delivery_state import DeliveryState, Outcome, StepResult
-
-AMBIGUITIES: tuple[dict[str, str], ...] = (
-    {
-        "code": "upstream_refine_failed",
-        "trigger": "`refine` outcome is not `success`",
-        "resolution": "re-run `/implement-ticket` from the start",
-    },
-    {
-        "code": "upstream_memory_failed",
-        "trigger": "`memory` outcome is not `success`",
-        "resolution": "re-run `/implement-ticket` from the start",
-    },
-    {
-        "code": "lost_ac",
-        "trigger": "ticket lost its `acceptance_criteria` between runs",
-        "resolution": "restart with the full ticket payload",
-    },
-)
-"""Declared ambiguity surfaces. Every BLOCKED return maps to one code."""
-
-
-def run(state: DeliveryState) -> StepResult:
-    """Return SUCCESS when upstream is coherent, BLOCKED otherwise."""
-    missing = _diagnose(state)
-    if not missing:
-        return StepResult(outcome=Outcome.SUCCESS)
-
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=_format_questions(ticket_id, missing),
-        message=(
-            f"Ticket {ticket_id} cannot enter the plan step: "
-            + "; ".join(missing)
-        ),
-    )
-
-
-def _diagnose(state: DeliveryState) -> list[str]:
-    """List the precondition failures in the order a reader needs them."""
-    issues: list[str] = []
-
-    if state.outcomes.get("refine") != Outcome.SUCCESS.value:
-        issues.append("refine step did not complete successfully")
-
-    if state.outcomes.get("memory") != Outcome.SUCCESS.value:
-        issues.append("memory step did not complete successfully")
-
-    ac = (state.ticket or {}).get("acceptance_criteria")
-    if not isinstance(ac, list) or not ac:
-        issues.append("ticket lost its acceptance criteria")
-
-    return issues
-
-
-def _format_questions(ticket_id: str, missing: list[str]) -> list[str]:
-    """Render the numbered options shown to the user when BLOCKED.
-
-    Two options: retry from the first failing step, or abort. The
-    headnote names the ticket and every failure so the user can
-    decide without re-reading the earlier output.
-    """
-    headnote = (
-        f"> Ticket {ticket_id} \u2014 analyze gate failed: "
-        + "; ".join(missing)
-        + "."
-    )
-    return [
-        headnote,
-        "> 1. Re-run `/implement-ticket` from the start \u2014 rebuild upstream state",
-        "> 2. Abort \u2014 the flow cannot continue",
-    ]
-
-
-__all__ = ["AMBIGUITIES", "run"]

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

@@ -1,145 +0,0 @@
-"""``implement`` step — gate + Option-A delegation for applying the plan.
-
-The step never edits files. Editing is delegated to the agent via
-``@agent-directive: apply-plan``; the agent runs the `minimal-safe-
-diff` and `scope-control` rules while it applies the plan, then
-writes the resulting file-level changes onto ``state.changes`` and
-marks ``outcomes['implement'] = 'success'`` before re-invoking the
-dispatcher.
-
-Flow:
-
-- ``plan`` outcome is not ``success`` → BLOCKED on precondition.
-- ``state.changes`` empty → BLOCKED with ``@agent-directive:
-  apply-plan`` so the agent applies the plan.
-- ``state.changes`` populated but malformed (entries missing
-  ``path``, or non-dict entries) → BLOCKED with shape complaint.
-- Otherwise → SUCCESS.
-
-``changes`` entries use the loose shape described in
-``docs/contracts/implement-ticket-flow.md#deliverystate-the-only-shared-object``
-\u2014 each entry is a dict with at least a ``path``; optional
-``lines`` / ``purpose`` feed the delivery report.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from ...delivery_state import (
-    DeliveryState,
-    Outcome,
-    StepResult,
-    agent_directive,
-)
-from ...persona_policy import resolve_policy
-
-AMBIGUITIES: tuple[dict[str, str], ...] = (
-    {
-        "code": "upstream_plan_failed",
-        "trigger": "`plan` outcome is not `success`",
-        "resolution": "re-run `/implement-ticket` from the start",
-    },
-    {
-        "code": "empty_changes_delegate",
-        "trigger": "`state.changes` empty — plan not applied yet",
-        "resolution": (
-            "agent directive `apply-plan` → edit under `minimal-safe-diff` "
-            "+ `scope-control`"
-        ),
-    },
-    {
-        "code": "malformed_changes",
-        "trigger": "any change entry is not a dict or has no non-empty `path`",
-        "resolution": "re-run `apply-plan` and resume",
-    },
-)
-"""Declared ambiguity surfaces. Advisory personas skip this step entirely."""
-
-
-def run(state: DeliveryState) -> StepResult:
-    """Gate on ``plan``, then either delegate or validate ``state.changes``."""
-    policy = resolve_policy(state.persona)
-    if not policy.allows_implement:
-        # Advisory personas produce a plan only; ``state.changes`` stays
-        # empty and the delivery report renders a "no file changes
-        # recorded" placeholder. See ``persona_policy`` for contract.
-        return StepResult(
-            outcome=Outcome.SUCCESS,
-            message=f"implement skipped: persona `{policy.name}` is plan-only.",
-        )
-
-    if state.outcomes.get("plan") != Outcome.SUCCESS.value:
-        return _blocked_on_precondition(state)
-
-    if not state.changes:
-        return _delegate_to_apply_plan(state)
-
-    shape_issues = _diagnose_changes(state.changes)
-    if shape_issues:
-        return _blocked_on_shape(state, shape_issues)
-
-    return StepResult(outcome=Outcome.SUCCESS)
-
-
-def _diagnose_changes(changes: list[Any]) -> list[str]:
-    """Every entry must be a dict carrying at least a non-empty ``path``."""
-    issues: list[str] = []
-    for idx, change in enumerate(changes, start=1):
-        if not isinstance(change, dict):
-            issues.append(f"change #{idx} is not a dict")
-            continue
-        path = change.get("path") or change.get("file")
-        if not isinstance(path, str) or not path.strip():
-            issues.append(f"change #{idx} has no path")
-    return issues
-
-
-def _delegate_to_apply_plan(state: DeliveryState) -> StepResult:
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=[
-            agent_directive("apply-plan", ticket=ticket_id),
-            f"> Ticket {ticket_id} \u2014 applying the recorded plan under "
-            "`minimal-safe-diff` + `scope-control`.",
-            "> 1. Continue \u2014 apply the plan as recorded",
-            "> 2. Abort \u2014 stop before any edits are made",
-        ],
-        message=f"Ticket {ticket_id} needs its plan applied before testing.",
-    )
-
-
-def _blocked_on_precondition(state: DeliveryState) -> StepResult:
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=[
-            f"> Ticket {ticket_id} \u2014 implement gate refused: "
-            "`plan` step did not complete successfully.",
-            "> 1. Re-run `/implement-ticket` from the start",
-            "> 2. Abort",
-        ],
-        message=(
-            f"Ticket {ticket_id} cannot implement: plan gate did not pass."
-        ),
-    )
-
-
-def _blocked_on_shape(state: DeliveryState, issues: list[str]) -> StepResult:
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=[
-            f"> Ticket {ticket_id} \u2014 recorded changes are malformed: "
-            + "; ".join(issues)
-            + ".",
-            "> 1. Re-run `apply-plan` and resume",
-            "> 2. Abort \u2014 changes cannot be trusted",
-        ],
-        message=(
-            f"Ticket {ticket_id} changes shape invalid: {'; '.join(issues)}."
-        ),
-    )
-
-
-__all__ = ["AMBIGUITIES", "run"]

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

@@ -1,136 +0,0 @@
-"""``memory`` step — bounded retrieval over the three allowed types.
-
-Contract (see
-``docs/contracts/implement-ticket-flow.md#memory-retrieval-contract``):
-
-- Three allowed types: ``domain-invariants``, ``incident-learnings``,
-  ``historical-patterns``. (Architectural rationale lives in ADRs —
-  ``docs/decisions/`` — not in curated memory.)
-- Hard cap of **12** hits total across the three types.
-- Keys derive from the ticket — title tokens plus acceptance-criterion
-  tokens plus any already-known ``files`` hint. Tokenisation is
-  deliberately naive (whitespace split, lower-cased) so the retrieval
-  shape stays reproducible in tests.
-- Step always returns ``SUCCESS``. Zero hits is a valid outcome
-  ("nothing in memory touches this ticket") — the ``report`` step
-  drops the memory section when that happens rather than padding.
-
-The step stores each hit as a plain ``dict`` on ``state.memory`` so
-consumers outside Python (the delivery report, JSON log lines) can
-round-trip the structure without pickling dataclasses.
-"""
-from __future__ import annotations
-
-import re
-from typing import Any, Iterable
-
-from ...delivery_state import DeliveryState, Outcome, StepResult
-
-MEMORY_TYPES: tuple[str, ...] = (
-    "domain-invariants",
-    "incident-learnings",
-    "historical-patterns",
-)
-"""The three types allowed by the flow contract. No aliases, no extras."""
-
-MAX_HITS: int = 12
-"""Hard cap per the roadmap — never raise without amending the contract."""
-
-AMBIGUITIES: tuple[dict[str, str], ...] = ()
-"""Memory retrieval always succeeds — zero hits is a valid outcome.
-
-Declared empty so the aggregate registry in ``steps/__init__.py``
-can round-trip every step's surfaces without a special case.
-"""
-
-_WORD = re.compile(r"[A-Za-z][A-Za-z0-9_\-]{2,}")
-_STOPWORDS = frozenset(
-    {
-        "the", "and", "for", "with", "from", "into", "that", "this",
-        "should", "must", "when", "then", "will", "have", "has",
-        "are", "was", "were", "can", "could", "would", "shall",
-        "also", "which", "where", "while", "make", "made", "use",
-        "used", "using", "user", "users", "test", "tests",
-    },
-)
-
-
-def run(state: DeliveryState) -> StepResult:
-    """Populate ``state.memory`` with up to :data:`MAX_HITS` hits."""
-    retrieve = _resolve_retrieve()
-    keys = _keys_from_ticket(state.ticket)
-    hits = retrieve(list(MEMORY_TYPES), keys, MAX_HITS)
-
-    # ``retrieve`` returns ``Hit`` dataclasses; coerce to dicts so the
-    # state is serialisation-ready for the report step and metrics log.
-    state.memory = [_as_dict(h) for h in hits[:MAX_HITS]]
-    return StepResult(outcome=Outcome.SUCCESS)
-
-
-def _resolve_retrieve():
-    """Import ``memory_lookup.retrieve`` lazily so tests can monkeypatch it.
-
-    Importing at module load time would freeze the reference before
-    tests can swap in a fake, which is the standard gotcha with the
-    ``from X import Y`` form. Deferring the import keeps the step
-    patchable from a single attribute (``memory_lookup.retrieve``).
-    """
-    import memory_lookup  # noqa: WPS433 — deliberately late import
-
-    return memory_lookup.retrieve
-
-
-def _keys_from_ticket(ticket: dict[str, Any]) -> list[str]:
-    """Derive retrieval keys from the ticket.
-
-    Three sources, in priority order so callers reading the log can
-    reconstruct why a hit scored: explicit ``files`` hints first,
-    then title tokens, then acceptance-criterion tokens. Duplicates
-    are removed while preserving first-seen order.
-    """
-    keys: list[str] = []
-    _extend_unique(keys, _as_str_list(ticket.get("files")))
-    _extend_unique(keys, _tokenise(ticket.get("title")))
-    for ac in _as_str_list(ticket.get("acceptance_criteria")):
-        _extend_unique(keys, _tokenise(ac))
-    return keys
-
-
-def _tokenise(value: Any) -> Iterable[str]:
-    """Return lower-cased content words from ``value`` (empty when absent)."""
-    if not isinstance(value, str):
-        return []
-    return [
-        match.group(0).lower()
-        for match in _WORD.finditer(value)
-        if match.group(0).lower() not in _STOPWORDS
-    ]
-
-
-def _as_str_list(value: Any) -> list[str]:
-    """Coerce ``value`` to a list of non-empty strings."""
-    if not isinstance(value, list):
-        return []
-    return [item for item in value if isinstance(item, str) and item.strip()]
-
-
-def _extend_unique(target: list[str], source: Iterable[str]) -> None:
-    """Append items from ``source`` to ``target`` skipping duplicates."""
-    seen = set(target)
-    for item in source:
-        if item in seen:
-            continue
-        target.append(item)
-        seen.add(item)
-
-
-def _as_dict(hit: Any) -> dict[str, Any]:
-    """Coerce a ``Hit`` (or pre-dict test fake) into a plain dict."""
-    as_dict = getattr(hit, "as_dict", None)
-    if callable(as_dict):
-        return as_dict()
-    if isinstance(hit, dict):
-        return dict(hit)
-    # Fallback path — should not happen in production, but keeps the
-    # step from crashing if a fixture returns a raw namespace object.
-    return {"entry": repr(hit)}

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

@@ -1,175 +0,0 @@
-"""``plan`` step — gate + delegation to ``feature-plan``.
-
-The dispatcher cannot synthesise a plan from pure Python: the real
-work needs code reading and judgement that only the agent has. The
-step therefore follows the Option-A delegation pattern described in
-``docs/contracts/implement-ticket-flow.md#agent-directives``:
-
-- ``state.plan`` empty → halt with ``BLOCKED`` and emit
-  ``@agent-directive: create-plan``. The orchestrator runs the
-  ``feature-plan`` skill, writes its output onto ``state.plan``,
-  marks ``outcomes['plan'] = 'success'``, and re-invokes the
-  dispatcher.
-
-- ``state.plan`` populated with a minimally valid shape → ``SUCCESS``
-  with no mutation. Shape validation catches accidental scaffolding
-  (e.g. an empty list, a placeholder string) that would produce a
-  broken plan downstream.
-
-- ``state.plan`` populated but malformed → ``BLOCKED`` with numbered
-  options so the user decides whether to re-plan, continue with the
-  malformed plan, or abort.
-
-``analyze`` is a precondition: the step refuses to plan when the
-upstream gate did not succeed, rather than silently re-running a
-derailed flow.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from ...delivery_state import (
-    DeliveryState,
-    Outcome,
-    StepResult,
-    agent_directive,
-)
-
-AMBIGUITIES: tuple[dict[str, str], ...] = (
-    {
-        "code": "upstream_analyze_failed",
-        "trigger": "`analyze` outcome is not `success`",
-        "resolution": "re-run `/implement-ticket` from the start",
-    },
-    {
-        "code": "empty_plan_delegate",
-        "trigger": "`state.plan` empty — no plan recorded yet",
-        "resolution": "agent directive `create-plan` → `/feature-plan`",
-    },
-    {
-        "code": "malformed_plan",
-        "trigger": (
-            "plan is not a non-empty string, list of strings/dicts, "
-            "or dict with a non-empty `steps` list"
-        ),
-        "resolution": "re-run `/feature-plan` or correct the recorded plan",
-    },
-)
-"""Declared ambiguity surfaces. Every BLOCKED return maps to one code."""
-
-
-def run(state: DeliveryState) -> StepResult:
-    """Gate on ``analyze``, then either delegate or validate the plan."""
-    if state.outcomes.get("analyze") != Outcome.SUCCESS.value:
-        return _blocked_on_precondition(state)
-
-    if _is_plan_empty(state.plan):
-        return _delegate_to_feature_plan(state)
-
-    shape_issues = _diagnose_shape(state.plan)
-    if shape_issues:
-        return _blocked_on_shape(state, shape_issues)
-
-    return StepResult(outcome=Outcome.SUCCESS)
-
-
-def _is_plan_empty(plan: Any) -> bool:
-    """True when ``state.plan`` has nothing a downstream step could use.
-
-    Whitespace-only strings count as empty \u2014 the user experience of
-    "nothing planned" is identical to "blank placeholder", and both
-    should delegate to ``feature-plan`` rather than fall through to
-    the shape-validator.
-    """
-    if plan is None:
-        return True
-    if isinstance(plan, str):
-        return not plan.strip()
-    if isinstance(plan, (list, dict, tuple, set)):
-        return len(plan) == 0
-    return False
-
-
-def _diagnose_shape(plan: Any) -> list[str]:
-    """Return the list of shape complaints against ``state.plan``.
-
-    Accepted shapes (matches ``report._format_plan``):
-    a non-empty string, a list of strings or ``{title, detail}`` dicts,
-    or a dict with a non-empty ``steps`` list. Everything else is
-    rejected so the report renderer never has to guess.
-    """
-    issues: list[str] = []
-
-    if isinstance(plan, str):
-        if not plan.strip():
-            issues.append("plan is a blank string")
-        return issues
-
-    if isinstance(plan, list):
-        if not plan:
-            issues.append("plan list is empty")
-            return issues
-        for idx, item in enumerate(plan, start=1):
-            if isinstance(item, dict):
-                if not (item.get("title") or item.get("step")):
-                    issues.append(f"plan step #{idx} has no title")
-            elif not isinstance(item, str) or not item.strip():
-                issues.append(f"plan step #{idx} is not a usable string")
-        return issues
-
-    if isinstance(plan, dict):
-        steps = plan.get("steps")
-        if not isinstance(steps, list) or not steps:
-            issues.append("plan dict must carry a non-empty 'steps' list")
-        return issues
-
-    issues.append(f"plan has unsupported type: {type(plan).__name__}")
-    return issues
-
-
-def _delegate_to_feature_plan(state: DeliveryState) -> StepResult:
-    """Halt with an agent directive so the orchestrator runs ``feature-plan``."""
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=[
-            agent_directive("create-plan", ticket=ticket_id),
-            f"> Ticket {ticket_id} \u2014 no plan recorded yet; running "
-            "`feature-plan` and resuming.",
-            "> 1. Continue \u2014 use the plan produced by `feature-plan`",
-            "> 2. Abort \u2014 stop before any edits are proposed",
-        ],
-        message=f"Ticket {ticket_id} needs a plan before implementation.",
-    )
-
-
-def _blocked_on_precondition(state: DeliveryState) -> StepResult:
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=[
-            f"> Ticket {ticket_id} \u2014 plan gate refused: "
-            "`analyze` step did not complete successfully.",
-            "> 1. Re-run `/implement-ticket` from the start",
-            "> 2. Abort",
-        ],
-        message=f"Ticket {ticket_id} cannot plan: analyze gate did not pass.",
-    )
-
-
-def _blocked_on_shape(state: DeliveryState, issues: list[str]) -> StepResult:
-    ticket_id = (state.ticket or {}).get("id") or "(no id)"
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=[
-            f"> Ticket {ticket_id} \u2014 recorded plan is malformed: "
-            + "; ".join(issues)
-            + ".",
-            "> 1. Re-run `feature-plan` and resume",
-            "> 2. Abort \u2014 the plan cannot be trusted",
-        ],
-        message=f"Ticket {ticket_id} plan shape invalid: {'; '.join(issues)}.",
-    )
-
-
-__all__ = ["AMBIGUITIES", "run"]