@event4u/agent-config 1.13.0 → 1.14.0

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

@@ -1,171 +0,0 @@
-"""Command-line entry point for ``/implement-ticket``.
-
-Minimal Option-A transport: the script loads a persisted
-``DeliveryState`` (or builds one from a ticket 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
-``agents/contexts/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.
-
-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 argparse
-import json
-import sys
-from dataclasses import asdict
-from pathlib import Path
-from typing import Sequence
-
-from .delivery_state import DeliveryState, Outcome
-from .dispatcher import dispatch
-from .steps import analyze, implement, memory, plan, refine, report, verify
-from .steps import test as test_step
-
-DEFAULT_STATE_FILE = Path(".implement-ticket-state.json")
-"""State file used when ``--state-file`` is not passed."""
-
-_STEPS = {
-    "refine": refine.run,
-    "memory": memory.run,
-    "analyze": analyze.run,
-    "plan": plan.run,
-    "implement": implement.run,
-    "test": test_step.run,
-    "verify": verify.run,
-    "report": report.run,
-}
-
-
-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
-
-    try:
-        state = _load_or_build(state_file, args)
-    except _CLIError as exc:
-        print(f"error: {exc}", file=sys.stderr)
-        return 2
-
-    final, halting = dispatch(state, _STEPS)
-    _save(state_file, state)
-    _emit(state, final, halting)
-    return 0 if final is Outcome.SUCCESS else 1
-
-
-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(
-        "--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.",
-    )
-    return parser
-
-
-def _load_or_build(state_file: Path, args: argparse.Namespace) -> DeliveryState:
-    """Return the state to dispatch against — either loaded or freshly built."""
-    if state_file.exists():
-        return _load(state_file)
-    if args.ticket_file is None:
-        raise _CLIError(
-            f"No state file at {state_file} and no --ticket-file given; "
-            "cannot build an initial DeliveryState.",
-        )
-    ticket = _read_json(args.ticket_file)
-    if not isinstance(ticket, dict):
-        raise _CLIError(
-            f"--ticket-file must carry a JSON object; got {type(ticket).__name__}.",
-        )
-    kwargs: dict = {"ticket": ticket}
-    if args.persona:
-        kwargs["persona"] = args.persona
-    return DeliveryState(**kwargs)
-
-
-def _load(state_file: Path) -> DeliveryState:
-    data = _read_json(state_file)
-    if not isinstance(data, dict):
-        raise _CLIError(
-            f"State file {state_file} must carry a JSON object; "
-            f"got {type(data).__name__}.",
-        )
-    try:
-        return DeliveryState(**data)
-    except TypeError as exc:
-        raise _CLIError(f"State file shape is invalid: {exc}") from exc
-
-
-def _save(state_file: Path, state: DeliveryState) -> None:
-    """Persist ``state`` as pretty JSON for diffing + human inspection."""
-    state_file.parent.mkdir(parents=True, exist_ok=True)
-    state_file.write_text(
-        json.dumps(asdict(state), indent=2, ensure_ascii=False) + "\n",
-        encoding="utf-8",
-    )
-
-
-def _read_json(path: Path):
-    try:
-        raw = path.read_text(encoding="utf-8")
-    except OSError as exc:
-        raise _CLIError(f"Cannot read {path}: {exc}") from exc
-    try:
-        return json.loads(raw)
-    except json.JSONDecodeError as exc:
-        raise _CLIError(f"Invalid JSON in {path}: {exc}") from exc
-
-
-def _emit(state: DeliveryState, final: Outcome, halting: str | None) -> None:
-    if final is Outcome.SUCCESS:
-        print(state.report)
-        return
-    print(f"[halt] outcome={final.value} step={halting or '(none)'}")
-    for line in state.questions:
-        print(line)
-
-
-class _CLIError(Exception):
-    """Raised on configuration or I/O problems. Converted to exit code 2."""
-
-
-__all__ = ["DEFAULT_STATE_FILE", "main"]

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"]