@event4u/agent-config 1.13.0 → 1.15.0

package/.agent-src/templates/scripts/implement_ticket/dispatcher.py

@@ -1,134 +0,0 @@
-"""Linear step dispatcher for ``/implement-ticket``.
-
-The dispatcher holds no business logic. It walks the fixed eight-step
-order declared in ``agents/contexts/implement-ticket-flow.md``, hands
-each step a live ``DeliveryState``, and honours the three terminal
-outcomes:
-
-- ``SUCCESS`` — record and advance.
-- ``BLOCKED`` — record, copy questions onto the state, halt.
-- ``PARTIAL`` — record, copy questions onto the state, halt.
-
-Resumption semantics (Option A, flow contract §agent-directives):
-steps whose name is already marked ``success`` in
-``state.outcomes`` are **skipped**. This lets a caller re-invoke the
-dispatcher after executing an agent-directive (the ``implement``,
-``test``, ``verify`` steps cannot run from pure Python), update the
-relevant slice of ``DeliveryState``, record ``success`` on the
-resumed step, and continue without replaying earlier work.
-
-Step handlers are injected by the caller rather than discovered at
-import time. Phase 1 shipped the dispatcher with mock handlers;
-Phase 2 wires the real ones under ``steps/``. Keeping injection
-explicit means the dispatcher is trivially testable and never
-depends on handler import order.
-"""
-from __future__ import annotations
-
-from collections.abc import Mapping
-
-from .delivery_state import DeliveryState, Outcome, Step, StepResult
-
-STEP_ORDER: tuple[str, ...] = (
-    "refine",
-    "memory",
-    "analyze",
-    "plan",
-    "implement",
-    "test",
-    "verify",
-    "report",
-)
-"""Canonical execution order. Eight steps, fixed, no branching.
-
-Changing this order is a roadmap-level decision — not a PR rider — per
-the surface-growth guardrails in
-``agents/roadmaps/road-to-implement-ticket.md``.
-"""
-
-
-def dispatch(
-    state: DeliveryState,
-    steps: Mapping[str, Step],
-) -> tuple[Outcome, str | None]:
-    """Run the eight steps linearly against ``state``.
-
-    Returns a ``(final_outcome, halting_step)`` tuple. ``halting_step``
-    is ``None`` when every step succeeded; otherwise it carries the
-    name of the step whose result halted the flow.
-
-    Parameters
-    ----------
-    state:
-        Live ``DeliveryState``. Mutated in place: each step's outcome
-        is recorded in ``state.outcomes`` under the step name, and
-        any surfaced questions land on ``state.questions``.
-    steps:
-        Mapping from step name to handler. Every entry in
-        :data:`STEP_ORDER` must be present; missing entries raise
-        ``KeyError`` at dispatch time rather than silently skipping,
-        so incomplete wiring surfaces as a hard failure.
-
-    Raises
-    ------
-    KeyError
-        If ``steps`` does not cover every entry in
-        :data:`STEP_ORDER`.
-    """
-    _assert_all_steps_present(steps)
-
-    # Clear stale questions from a previous halt before we resume so
-    # the caller never mistakes old options for fresh ones.
-    state.questions = []
-
-    for name in STEP_ORDER:
-        if state.outcomes.get(name) == Outcome.SUCCESS.value:
-            # Already completed on an earlier invocation — skip per the
-            # resume contract. The caller is responsible for keeping
-            # ``state.outcomes`` and the matching slice in sync.
-            continue
-
-        handler = steps[name]
-        result = handler(state)
-        _validate_step_result(name, result)
-
-        state.outcomes[name] = result.outcome.value
-
-        if result.outcome is Outcome.BLOCKED:
-            state.questions = list(result.questions)
-            return Outcome.BLOCKED, name
-
-        if result.outcome is Outcome.PARTIAL:
-            state.questions = list(result.questions)
-            return Outcome.PARTIAL, name
-
-    return Outcome.SUCCESS, None
-
-
-def _assert_all_steps_present(steps: Mapping[str, Step]) -> None:
-    """Reject an incomplete step mapping up front.
-
-    We deliberately fail loudly here: a missing step would otherwise
-    raise deep inside the dispatch loop after partial state mutation,
-    which makes debugging the wiring harder than it needs to be.
-    """
-    missing = [name for name in STEP_ORDER if name not in steps]
-    if missing:
-        raise KeyError(
-            "Step mapping is missing handlers for: " + ", ".join(missing),
-        )
-
-
-def _validate_step_result(name: str, result: StepResult) -> None:
-    """Enforce the blocked/partial invariant: questions must be set.
-
-    A step that blocks without surfacing a question is a bug — there
-    is nothing for the user to answer. We raise ``ValueError`` instead
-    of silently recording the outcome so the defect is visible at the
-    earliest possible point.
-    """
-    if result.outcome in (Outcome.BLOCKED, Outcome.PARTIAL) and not result.questions:
-        raise ValueError(
-            f"Step {name!r} returned {result.outcome.value} with no questions; "
-            "blocked and partial outcomes must surface at least one numbered option.",
-        )

package/.agent-src/templates/scripts/implement_ticket/steps/__init__.py

@@ -1,49 +0,0 @@
-"""Step handlers for the ``/implement-ticket`` dispatcher.
-
-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.
-
-Phase 2 ships all eight step handlers. 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 ``agents/contexts/implement-ticket-flow.md`` for the
-slice contracts each handler writes to.
-"""
-from __future__ import annotations
-
-from . import analyze, implement, memory, plan, refine, report, test, verify
-
-_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}
-
-
-__all__ = [
-    "all_ambiguities",
-    "analyze",
-    "implement",
-    "memory",
-    "plan",
-    "refine",
-    "report",
-    "test",
-    "verify",
-]

package/.agent-src/templates/scripts/implement_ticket/steps/refine.py

@@ -1,140 +0,0 @@
-"""``refine`` step — deterministic gate in front of the ``refine-ticket`` skill.
-
-The step never calls an LLM. It inspects ``state.ticket`` for the
-minimum viable shape (an identifier, a non-trivial title, and at
-least one sufficiently concrete acceptance criterion) and either:
-
-- returns ``SUCCESS`` — the ticket is already refined enough for the
-  downstream steps to plan against, or
-- returns ``BLOCKED`` — the deficiencies are listed as numbered
-  options per the ``user-interaction`` rule, and the flow halts so
-  the user can run ``/refine-ticket`` (or provide the missing data)
-  and re-invoke ``/implement-ticket``.
-
-The checks live here (rather than inside the ``refine-ticket`` skill)
-because the dispatcher is synchronous Python: it cannot "delegate"
-to an agent skill mid-loop. Making the gate deterministic keeps the
-contract "block on ambiguity, never guess" enforceable from code,
-and leaves the harder judgement calls (is an AC measurable? testable?)
-to the human-run ``/refine-ticket`` flow on the rebound.
-"""
-from __future__ import annotations
-
-from typing import Any
-
-from ..delivery_state import DeliveryState, Outcome, StepResult
-
-_MIN_TITLE_LEN = 3
-_MIN_AC_LEN = 10
-
-AMBIGUITIES: tuple[dict[str, str], ...] = (
-    {
-        "code": "missing_id",
-        "trigger": "ticket has no `id` field (or only whitespace)",
-        "resolution": "run `/refine-ticket` or paste the ticket id in chat",
-    },
-    {
-        "code": "trivial_title",
-        "trigger": f"title missing or shorter than {_MIN_TITLE_LEN} chars",
-        "resolution": "run `/refine-ticket` to rewrite the title",
-    },
-    {
-        "code": "missing_or_vague_ac",
-        "trigger": (
-            f"acceptance_criteria empty, non-list, or any item under "
-            f"{_MIN_AC_LEN} chars"
-        ),
-        "resolution": "run `/refine-ticket` to add concrete acceptance criteria",
-    },
-)
-"""Declared ambiguity surfaces. Every BLOCKED return maps to one code."""
-
-
-def run(state: DeliveryState) -> StepResult:
-    """Return SUCCESS when the ticket is refined, BLOCKED otherwise."""
-    deficiencies = _diagnose(state.ticket)
-    if not deficiencies:
-        return StepResult(outcome=Outcome.SUCCESS)
-
-    ticket_id = state.ticket.get("id") or "(no id)"
-    questions = _format_questions(ticket_id, deficiencies)
-    return StepResult(
-        outcome=Outcome.BLOCKED,
-        questions=questions,
-        message=(
-            f"Ticket {ticket_id} is not refined enough to plan against: "
-            + "; ".join(deficiencies)
-        ),
-    )
-
-
-def _diagnose(ticket: dict[str, Any]) -> list[str]:
-    """Return a human-readable list of what's missing from the ticket.
-
-    Order matches what a reader needs first (identity → summary →
-    acceptance criteria) so the surfaced questions read naturally.
-    """
-    issues: list[str] = []
-
-    ticket_id = ticket.get("id")
-    if not isinstance(ticket_id, str) or not ticket_id.strip():
-        issues.append("missing ticket id")
-
-    title = ticket.get("title")
-    if not isinstance(title, str) or len(title.strip()) < _MIN_TITLE_LEN:
-        issues.append("missing or trivial title")
-
-    ac = ticket.get("acceptance_criteria")
-    if not isinstance(ac, list) or not ac:
-        issues.append("no acceptance criteria")
-    else:
-        weak_indices = [
-            idx + 1
-            for idx, item in enumerate(ac)
-            if not _is_concrete_ac(item)
-        ]
-        if weak_indices:
-            issues.append(
-                "vague acceptance criteria at position(s) "
-                + ", ".join(str(i) for i in weak_indices),
-            )
-
-    return issues
-
-
-def _is_concrete_ac(item: Any) -> bool:
-    """An AC is concrete when it is a non-empty string above the length floor.
-
-    The floor is deliberately loose: refine is a gate, not a style
-    judge. The heavy lifting (measurability, testability, tone) is
-    owned by the ``refine-ticket`` skill on the rebound.
-    """
-    if not isinstance(item, str):
-        return False
-    return len(item.strip()) >= _MIN_AC_LEN
-
-
-def _format_questions(ticket_id: str, deficiencies: list[str]) -> list[str]:
-    """Render the numbered options shown to the user when BLOCKED.
-
-    Three options, ordered by likely next action: run the existing
-    refinement skill, paste the missing data in chat, or abandon the
-    ticket entirely. ``user-interaction`` requires numbered, prose-
-    free options; the deficiency list is rendered as a headnote.
-    """
-    headnote = (
-        "> Ticket "
-        + ticket_id
-        + " is missing: "
-        + "; ".join(deficiencies)
-        + "."
-    )
-    return [
-        headnote,
-        f"> 1. Run `/refine-ticket {ticket_id}` and re-invoke `/implement-ticket`",
-        "> 2. Provide the missing details in chat — I'll merge them into the ticket",
-        "> 3. Abandon this ticket — too vague to implement",
-    ]
-
-
-__all__ = ["AMBIGUITIES", "run"]