@event4u/agent-config 1.9.1

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

@@ -0,0 +1,171 @@
+"""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/delivery_state.py

@@ -0,0 +1,130 @@
+"""``DeliveryState`` — the only object shared between orchestrator steps.
+
+The shape mirrors ``agents/contexts/implement-ticket-flow.md``. No step
+may invent fields not declared here; extensions require a roadmap
+amendment plus a flow-contract update.
+
+Steps return a ``StepResult`` with one of three ``Outcome`` values:
+
+- ``SUCCESS``  — step populated its slice of ``DeliveryState`` and the
+  dispatcher continues to the next step.
+- ``BLOCKED``  — step hit an ambiguity it cannot resolve on its own.
+  ``questions`` carries pre-formatted numbered options per the
+  ``user-interaction`` rule. The dispatcher halts.
+- ``PARTIAL``  — step populated its slice *and* produced open
+  questions. The dispatcher halts with the same surface as BLOCKED;
+  the calling orchestrator (Phase 3) decides whether to prompt the
+  user to continue or stop.
+
+``DeliveryState`` is a plain dataclass rather than a typed dict so
+step handlers can rely on attribute access, defaults, and mutation
+semantics without resorting to dictionary indirection.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable
+
+
+class Outcome(str, Enum):
+    """Terminal outcome of a single step.
+
+    Subclassing ``str`` keeps JSON serialisation trivial (Outcome
+    values round-trip as their string form) without hand-rolling a
+    ``__str__`` override.
+    """
+
+    SUCCESS = "success"
+    BLOCKED = "blocked"
+    PARTIAL = "partial"
+
+
+@dataclass
+class StepResult:
+    """Return value of a single ``Step`` invocation.
+
+    ``questions`` is only populated for ``BLOCKED`` / ``PARTIAL``
+    outcomes. Each entry is a fully-formatted numbered line so the
+    dispatcher can surface them verbatim without reformatting.
+    """
+
+    outcome: Outcome
+    questions: list[str] = field(default_factory=list)
+    message: str = ""
+
+
+@dataclass
+class DeliveryState:
+    """Canonical state passed between orchestrator steps.
+
+    Field order matches the table in
+    ``agents/contexts/implement-ticket-flow.md``. Mutable defaults use
+    ``field(default_factory=...)`` so every instance owns its own
+    containers — a single shared list across runs would be a
+    cross-run contamination hazard for the metrics pipeline.
+    """
+
+    ticket: dict[str, Any]
+    persona: str = "senior-engineer"
+    memory: list[dict[str, Any]] = field(default_factory=list)
+    plan: Any = None
+    changes: list[dict[str, Any]] = field(default_factory=list)
+    tests: Any = None
+    verify: Any = None
+    outcomes: dict[str, str] = field(default_factory=dict)
+    questions: list[str] = field(default_factory=list)
+    report: str = ""
+
+
+Step = Callable[[DeliveryState], StepResult]
+"""Protocol every step handler must satisfy.
+
+A step reads and writes ``DeliveryState`` in place; its return value
+carries only the terminal ``Outcome`` and any surfaced questions.
+"""
+
+
+AGENT_DIRECTIVE_PREFIX = "@agent-directive:"
+"""Marker that flags a ``questions[0]`` entry as agent-addressed, not user-addressed.
+
+When a step cannot run deterministically from pure Python (edits,
+subprocess calls, anything that needs tools the dispatcher doesn't
+own), it returns ``BLOCKED`` with this prefix as the first entry of
+``questions``. The orchestrator reads it and drives the matching
+skill; the user-facing numbered options follow on subsequent lines.
+
+The prefix is public contract: changing it breaks every agent that
+has learned to recognise it. See
+``agents/contexts/implement-ticket-flow.md#agent-directives``.
+"""
+
+
+def agent_directive(name: str, **payload: Any) -> str:
+    """Format a canonical ``@agent-directive:`` line.
+
+    ``name`` is the directive verb the agent dispatches on (for
+    example ``"implement-plan"`` or ``"run-tests"``). ``payload``
+    entries are rendered as ``key=value`` pairs on the same line, so
+    the whole directive stays a single greppable string. Values are
+    coerced with ``str`` — richer payloads belong on the
+    ``DeliveryState`` itself, not in the directive line.
+    """
+    suffix = " ".join(f"{key}={value}" for key, value in payload.items())
+    return (
+        f"{AGENT_DIRECTIVE_PREFIX} {name} {suffix}".strip()
+        if suffix
+        else f"{AGENT_DIRECTIVE_PREFIX} {name}"
+    )
+
+
+def is_agent_directive(question: str) -> bool:
+    """True when ``question`` is an agent-addressed directive line.
+
+    Used by the orchestrator to split ``state.questions`` into the
+    agent-facing directive (at most one, always at index 0) and the
+    user-facing numbered options (everything else).
+    """
+    return isinstance(question, str) and question.lstrip().startswith(
+        AGENT_DIRECTIVE_PREFIX,
+    )

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

@@ -0,0 +1,134 @@
+"""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/persona_policy.py

@@ -0,0 +1,85 @@
+"""Persona policy — behavioural parameters resolved from ``state.persona``.
+
+Three personas ship today, each keyed by the string already carried
+on ``DeliveryState.persona`` (see
+``agents/contexts/implement-ticket-flow.md#personas``):
+
+``senior-engineer``
+    Default. Runs every step. No test widening.
+``qa``
+    Runs every step but widens the ``test`` scope to the full suite
+    (``scope=full`` in the ``run-tests`` directive) so regressions
+    outside the changed paths are caught.
+``advisory``
+    Plan-only mode. ``implement``, ``test``, and ``verify`` short-
+    circuit to SUCCESS without doing work — the flow produces a
+    delivery report whose value is the plan itself, and next-command
+    suggestions are suppressed (nothing was committed).
+
+Unknown persona names fall back to ``senior-engineer`` rather than
+raising, so a mistyped value never aborts a run mid-flight. The
+caller is responsible for validating the string at the state-
+construction boundary if strict behaviour is needed.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+DEFAULT_PERSONA = "senior-engineer"
+"""Name used when ``state.persona`` is empty or unrecognised."""
+
+
+@dataclass(frozen=True)
+class PersonaPolicy:
+    """Behavioural flags read by individual step handlers.
+
+    Frozen so a step cannot mutate the policy mid-run by accident —
+    policy is resolved once and treated as read-only configuration.
+    """
+
+    name: str
+    allows_implement: bool = True
+    allows_test: bool = True
+    allows_verify: bool = True
+    widen_tests: bool = False
+    suggests_next_commands: bool = True
+
+
+_POLICIES: dict[str, PersonaPolicy] = {
+    "senior-engineer": PersonaPolicy(name="senior-engineer"),
+    "qa": PersonaPolicy(name="qa", widen_tests=True),
+    "advisory": PersonaPolicy(
+        name="advisory",
+        allows_implement=False,
+        allows_test=False,
+        allows_verify=False,
+        suggests_next_commands=False,
+    ),
+}
+
+
+def resolve_policy(persona: Any) -> PersonaPolicy:
+    """Return the policy for ``persona``; fall back to the default on miss.
+
+    ``persona`` is typed ``Any`` because it originates from
+    ``DeliveryState.persona`` which the dataclass declares as ``str``
+    but does not enforce — a caller may set it to ``None`` while
+    wiring up a partial state in tests.
+    """
+    if isinstance(persona, str) and persona in _POLICIES:
+        return _POLICIES[persona]
+    return _POLICIES[DEFAULT_PERSONA]
+
+
+def known_personas() -> tuple[str, ...]:
+    """Return the persona names shipped today, in insertion order."""
+    return tuple(_POLICIES.keys())
+
+
+__all__ = [
+    "DEFAULT_PERSONA",
+    "PersonaPolicy",
+    "known_personas",
+    "resolve_policy",
+]

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

@@ -0,0 +1,49 @@
+"""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/analyze.py

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