@event4u/agent-config 1.9.1

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

@@ -0,0 +1,145 @@
+"""``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
+``agents/contexts/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/.agent-src/templates/scripts/implement_ticket/steps/memory.py

@@ -0,0 +1,136 @@
+"""``memory`` step — bounded retrieval over the four allowed types.
+
+Contract (see
+``agents/contexts/implement-ticket-flow.md#memory-retrieval-contract``):
+
+- Four allowed types: ``domain-invariants``, ``architecture-decisions``,
+  ``incident-learnings``, ``historical-patterns``.
+- Hard cap of **12** hits total across the four 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",
+    "architecture-decisions",
+    "incident-learnings",
+    "historical-patterns",
+)
+"""The four 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/.agent-src/templates/scripts/implement_ticket/steps/plan.py

@@ -0,0 +1,175 @@
+"""``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
+``agents/contexts/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"]

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

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