@event4u/agent-config 1.13.0 → 1.14.0

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

@@ -0,0 +1,116 @@
+"""Mixed (backend + UI) directive set — Phase 4 wiring.
+
+Phase 4 of ``agents/roadmaps/road-to-product-ui-track.md``: ``mixed`` is
+the directive set for tickets that touch both layers. Its plan slot
+locks the backend contract (data shape + API surface) before any UI
+work begins; its implement slot delegates the full UI sub-flow once
+the contract is confirmed; its test slot stitches the seam with
+end-to-end smoke scenarios.
+
+Slot mapping (mirrors :mod:`work_engine.directives.backend.get_steps`):
+
+- ``refine`` → :mod:`work_engine.directives.backend.refine` — intent
+  classification + ticket / prompt gate (shared with backend).
+- ``memory`` → :mod:`work_engine.directives.backend.memory` —
+  engineering-memory pull (shared with backend).
+- ``analyze`` → :mod:`work_engine.directives.backend.analyze` —
+  backend analysis precondition for the contract lock.
+- ``plan`` → :mod:`.contract` — backend contract lock (Phase 4 Step 1).
+- ``implement`` → :mod:`.ui` — delegate to UI sub-flow (Phase 4 Step 2).
+- ``test`` → :mod:`.stitch` — integration verification (Phase 4 Step 3).
+- ``verify`` → :mod:`work_engine.directives.backend.verify` — four-judge
+  review on the merged diff (shared with backend).
+- ``report`` → :mod:`work_engine.directives.backend.report` — delivery
+  markdown (shared with backend).
+
+The shared steps are reused by reference, not by duplication: the
+backend versions already gate on ``test`` / ``verify`` outcomes via
+the dispatcher's ``state.outcomes`` dict, so they slot into the mixed
+flow without modification.
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from ...delivery_state import Step
+from ..backend import analyze as backend_analyze
+from ..backend import memory as backend_memory
+from ..backend import refine as backend_refine
+from ..backend import report as backend_report
+from ..backend import verify as backend_verify
+from . import contract, stitch, ui
+
+DIRECTIVE_SET_NAME = "mixed"
+"""External name carried in ``state.directive_set`` for this set."""
+
+ROADMAP = "agents/roadmaps/road-to-product-ui-track.md"
+"""Roadmap that promotes the Phase 4 stub to working handlers."""
+
+SUPPORTED_KINDS: tuple[str, ...] = ("ticket", "prompt")
+"""Input kinds this directive set accepts.
+
+``mixed`` accepts the same envelope shapes as ``backend``: ticket
+payloads (refined by the ticket flow) and free-form prompts
+(refined by ``refine-prompt``). The ``diff`` / ``file`` envelopes
+stay UI-only since they describe an existing screen, not a backend
+contract surface.
+"""
+
+
+def _build_step_map() -> dict[str, Step]:
+    """Wire the eight-step dispatcher slots for the mixed set.
+
+    ``refine`` / ``memory`` / ``analyze`` / ``verify`` / ``report``
+    reuse the backend handlers verbatim; ``plan`` / ``implement`` /
+    ``test`` are the mixed-specific contract → ui → stitch chain.
+    """
+    return {
+        "refine": backend_refine.run,
+        "memory": backend_memory.run,
+        "analyze": backend_analyze.run,
+        "plan": contract.run,
+        "implement": ui.run,
+        "test": stitch.run,
+        "verify": backend_verify.run,
+        "report": backend_report.run,
+    }
+
+
+def get_steps() -> Mapping[str, Step]:
+    """Return the ``{step_name: handler}`` mapping the dispatcher walks.
+
+    Mirrors :func:`work_engine.directives.backend.get_steps` and
+    :func:`work_engine.directives.ui.get_steps`.
+    """
+    return _build_step_map()
+
+
+def all_ambiguities() -> dict[str, tuple[dict[str, str], ...]]:
+    """Per-step ambiguity declarations.
+
+    Each handler re-exports its own ``AMBIGUITIES`` tuple. The mapping
+    is rebuilt per call (cheap; documentation generators and the
+    ``test_ambiguity_coverage`` suite invoke this once per run).
+    """
+    return {
+        "refine": backend_refine.AMBIGUITIES,
+        "memory": backend_memory.AMBIGUITIES,
+        "analyze": backend_analyze.AMBIGUITIES,
+        "plan": contract.AMBIGUITIES,
+        "implement": ui.AMBIGUITIES,
+        "test": stitch.AMBIGUITIES,
+        "verify": backend_verify.AMBIGUITIES,
+        "report": backend_report.AMBIGUITIES,
+    }
+
+
+__all__ = [
+    "DIRECTIVE_SET_NAME",
+    "ROADMAP",
+    "SUPPORTED_KINDS",
+    "all_ambiguities",
+    "contract",
+    "get_steps",
+    "stitch",
+    "ui",
+]

package/.agent-src/templates/scripts/work_engine/directives/mixed/contract.py

@@ -0,0 +1,254 @@
+"""``contract`` step — locks data_model + api_surface before any UI work.
+
+Phase 4 Step 1 of ``agents/roadmaps/road-to-product-ui-track.md``: in the
+``mixed`` directive set the ``plan`` slot is the contract step. It
+resolves the **backend contract** the UI will consume — entity shape,
+endpoint signatures, validation surface — *before* the UI track runs.
+The mixed ``ui`` step gates on ``state.contract.contract_confirmed is
+True``; without that sentinel the UI directive refuses to start (per
+roadmap risk: "Mixed flow's contract halt is bypassed").
+
+Routes on ``state.contract`` shape:
+
+- **Empty / None** — first pass. Emit ``@agent-directive: contract-plan``
+  delegating to ``feature-plan`` with a contract-only scope; on the
+  rebound the contract lands in ``state.contract``.
+- **Populated, missing required keys** — halt listing the gaps
+  (``data_model``, ``api_surface``) so the next pass writes the slots
+  the UI will read.
+- **Populated, well-formed, ``contract_confirmed`` missing or False** —
+  halt with a numbered-options summary so the user signs off on the
+  contract before any UI work begins.
+- **Populated, well-formed, ``contract_confirmed`` True** — return
+  ``SUCCESS``; the dispatcher advances to the mixed ``ui`` step.
+
+``analyze`` is a precondition: the step refuses to plan a contract
+when the upstream gate did not succeed, mirroring ``backend.plan``.
+
+Idempotent: a re-entry with ``contract_confirmed=True`` round-trips
+through ``SUCCESS`` without re-emitting a halt the user already
+answered.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...delivery_state import (
+    DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+)
+
+REQUIRED_CONTRACT_KEYS: tuple[str, ...] = (
+    "data_model",
+    "api_surface",
+)
+"""Top-level keys every well-formed contract must carry.
+
+``data_model`` lists the entities (and their fields) the UI will
+read or write. ``api_surface`` lists the endpoints / actions the UI
+will call. Both are non-empty lists when populated; the schema
+validator in ``state._validate_contract`` enforces only the type, the
+content check lives here.
+"""
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "upstream_analyze_failed",
+        "trigger": "`analyze` outcome is not `success`",
+        "resolution": "re-run the mixed flow from the start",
+    },
+    {
+        "code": "contract_missing",
+        "trigger": "state.contract is None or empty — contract has not been produced",
+        "resolution": "agent directive `contract-plan` → `feature-plan` skill "
+        "writes the contract into state.contract",
+    },
+    {
+        "code": "contract_incomplete",
+        "trigger": "contract is populated but missing required keys "
+        "(`data_model`, `api_surface`) or one of them is empty",
+        "resolution": "agent re-runs `feature-plan` with contract-only scope; "
+        "halt lists the missing slots",
+    },
+    {
+        "code": "contract_unconfirmed",
+        "trigger": "contract is well-formed but contract_confirmed is unset/False",
+        "resolution": "user reviews the contract summary and sets "
+        "state.contract.contract_confirmed = True (or asks for "
+        "revisions, which loops back to contract-plan)",
+    },
+)
+"""Declared ambiguity surfaces. Every BLOCKED return maps to one code."""
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Apply the contract-first lock to ``state.contract``."""
+    if state.outcomes.get("analyze") != Outcome.SUCCESS.value:
+        return _blocked_on_precondition(state)
+
+    contract = state.contract
+    if not _is_populated(contract):
+        return _delegate_to_feature_plan(state)
+
+    missing = _missing_required_keys(contract)
+    if missing:
+        return _halt_incomplete_contract(state, missing)
+
+    if contract.get("contract_confirmed") is True:
+        return StepResult(outcome=Outcome.SUCCESS)
+
+    return _halt_unconfirmed(state, contract)
+
+
+def _is_populated(contract: Any) -> bool:
+    """True when ``contract`` carries an actionable backend lock.
+
+    Non-dict and empty-dict shapes are treated as "skill has not run"
+    so the first-pass directive fires. Once the skill writes a
+    contract, the dict carries at least one of the required keys;
+    from there :func:`_missing_required_keys` decides whether the
+    contract is complete enough to advance.
+    """
+    if not isinstance(contract, dict):
+        return False
+    if not contract:
+        return False
+    return any(key in contract for key in REQUIRED_CONTRACT_KEYS)
+
+
+def _missing_required_keys(contract: dict[str, Any]) -> list[str]:
+    """Return required top-level keys that are missing or empty.
+
+    Schema validation (``state._validate_contract``) already rejects
+    non-list ``data_model`` / ``api_surface``; here we treat empty
+    lists the same as missing — an empty data model or an empty
+    surface gives the UI nothing to consume.
+    """
+    missing: list[str] = []
+    for key in REQUIRED_CONTRACT_KEYS:
+        value = contract.get(key)
+        if value is None or value == [] or value == {}:
+            missing.append(key)
+    return missing
+
+
+def _preview_input(state: DeliveryState) -> str:
+    """Render a one-line preview of the input being contracted."""
+    data = state.ticket or {}
+    raw = data.get("raw")
+    if isinstance(raw, str) and raw.strip():
+        text = " ".join(raw.split())
+    else:
+        title = data.get("title")
+        text = title if isinstance(title, str) else (data.get("id") or "(no title)")
+    if len(text) <= 80:
+        return text
+    return text[:79].rstrip() + "\u2026"
+
+
+def _blocked_on_precondition(state: DeliveryState) -> StepResult:
+    """BLOCKED halt \u2014 upstream ``analyze`` did not succeed."""
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            "> `analyze` did not succeed; cannot lock the contract until "
+            "the upstream investigation lands.",
+            "> 1. Re-run \u2014 restart the mixed flow from the start",
+            "> 2. Abort \u2014 drop this request",
+        ],
+        message="contract step gated on analyze; upstream outcome is not success.",
+    )
+
+
+def _delegate_to_feature_plan(state: DeliveryState) -> StepResult:
+    """Halt with an agent directive so the orchestrator runs ``feature-plan``.
+
+    The directive carries a ``contract-only`` scope marker so the
+    skill produces just the data model and API surface \u2014 no UI
+    plan yet (Phase 4 Step 2 owns that).
+    """
+    preview = _preview_input(state)
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive("contract-plan"),
+            f"> Input: {preview}",
+            "> No backend contract yet \u2014 producing one now. The contract "
+            "locks the data model and API surface the UI will consume; "
+            "the mixed `ui` step refuses to start without it.",
+            "> Scope: contract-only (no UI plan, no implementation).",
+            "> 1. Continue \u2014 produce the contract via `feature-plan`",
+            "> 2. Abort \u2014 drop this mixed request",
+        ],
+        message="Mixed contract missing; delegating to feature-plan (contract-only).",
+    )
+
+
+def _halt_incomplete_contract(
+    state: DeliveryState,
+    missing: list[str],
+) -> StepResult:
+    """BLOCKED halt \u2014 contract is missing required keys."""
+    preview = _preview_input(state)
+    lines = [
+        agent_directive("contract-plan"),
+        f"> Input: {preview}",
+        "> Backend contract is incomplete. Missing required slots:",
+    ]
+    for path in missing:
+        lines.append(f"> - `{path}`")
+    lines.append(
+        "> Re-run `feature-plan` (contract-only) so every required slot "
+        "has a final value before the UI track starts.",
+    )
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=lines,
+        message=(
+            f"Mixed contract incomplete; {len(missing)} required slot(s) missing."
+        ),
+    )
+
+
+def _halt_unconfirmed(
+    state: DeliveryState,
+    contract: dict[str, Any],
+) -> StepResult:
+    """BLOCKED halt \u2014 contract is well-formed; user must sign off."""
+    preview = _preview_input(state)
+    data_model = contract.get("data_model") or []
+    api_surface = contract.get("api_surface") or []
+
+    entity_count = len(data_model) if isinstance(data_model, list) else 0
+    endpoint_count = len(api_surface) if isinstance(api_surface, list) else 0
+
+    lines = [
+        f"> Input: {preview}",
+        "> Backend contract is ready. Summary:",
+        f"> - Entities (data model): {entity_count}",
+        f"> - Endpoints / actions (api surface): {endpoint_count}",
+        "> 1. Confirm \u2014 lock this contract and advance to the UI track",
+        "> 2. Revise \u2014 send feedback; loops back to `contract-plan`",
+        "> 3. Abort \u2014 drop this mixed request",
+        "",
+        "**Recommendation: 1 \u2014 Confirm** \u2014 the contract covers both "
+        "required slots. Caveat: flip to 2 only if an entity field or "
+        "endpoint signature is wrong; the UI track will treat this "
+        "contract as immutable input.",
+    ]
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=lines,
+        message=(
+            "Mixed contract ready; halting for user confirmation before UI track."
+        ),
+    )
+
+
+__all__ = [
+    "AMBIGUITIES",
+    "REQUIRED_CONTRACT_KEYS",
+    "run",
+]

package/.agent-src/templates/scripts/work_engine/directives/mixed/stitch.py

@@ -0,0 +1,229 @@
+"""``stitch`` step — integration verification across the contract / UI seam.
+
+Phase 4 Step 3 of ``agents/roadmaps/road-to-product-ui-track.md``: in the
+``mixed`` directive set the ``test`` slot is the integration boundary.
+The dispatcher does not run integration scenarios itself — the agent
+invokes the ``integration-test`` skill which drives end-to-end smokes
+(fill form → server validation → response → UI update) and writes the
+verdict back to ``state.stitch``.
+
+``state.stitch`` contract when populated:
+
+- Must be a dict.
+- Must carry a ``verdict`` key — one of ``success``, ``blocked``,
+  ``partial`` (mirrors the ``Outcome`` vocabulary used in
+  ``backend.verify``).
+- Optional ``scenarios`` list documents the smoke cases run.
+- Optional ``integration_confirmed`` boolean — when ``True``, the user
+  has signed off on a partial / blocked verdict and the flow may
+  advance regardless. Treated as an explicit override.
+
+Routing:
+
+- **Upstream ``implement`` (mixed.ui) outcome not success** — refuse;
+  the contract / UI handoff did not complete.
+- **``state.stitch`` empty** — emit ``@agent-directive: integration-test``
+  so the orchestrator runs the smoke scenarios.
+- **Stitch shape malformed** — halt for re-run; verdict cannot be
+  trusted.
+- **Verdict ``success``** — return ``SUCCESS``; dispatcher advances to
+  ``verify``.
+- **Verdict ``blocked`` / ``partial`` and not user-confirmed** — halt
+  with three numbered options (fix / override / abort).
+- **Verdict ``blocked`` / ``partial`` and ``integration_confirmed=True``**
+  — return ``SUCCESS`` (explicit user override).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...delivery_state import (
+    DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+)
+
+INTEGRATION_TEST_DIRECTIVE = "integration-test"
+"""Agent directive that drives end-to-end smoke scenarios.
+
+The skill fills forms, hits the locked endpoints, and asserts the UI
+reflects the response. It writes ``state.stitch`` with a verdict and
+the list of scenarios it ran. The mixed flow routes on the verdict.
+"""
+
+_ALLOWED_VERDICTS = ("success", "blocked", "partial")
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "upstream_ui_failed",
+        "trigger": "`implement` (mixed.ui) outcome is not `success`",
+        "resolution": "re-run the mixed flow; UI track must finish before stitch",
+    },
+    {
+        "code": "empty_stitch_delegate",
+        "trigger": "`state.stitch` empty — integration-test skill has not run yet",
+        "resolution": "agent directive `integration-test` → end-to-end smokes",
+    },
+    {
+        "code": "malformed_stitch",
+        "trigger": (
+            "`state.stitch` is not a dict or `verdict` is not one of "
+            "success / blocked / partial"
+        ),
+        "resolution": "re-run `integration-test` and record a clean verdict",
+    },
+    {
+        "code": "bad_stitch_verdict",
+        "trigger": "`state.stitch['verdict']` is `blocked` or `partial` "
+        "and `integration_confirmed` is not True",
+        "resolution": (
+            "address findings and re-run `integration-test`, or set "
+            "`integration_confirmed=True` to override (rare)"
+        ),
+    },
+)
+"""Declared ambiguity surfaces. Every BLOCKED return maps to one code."""
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Gate on ``implement``, then validate ``state.stitch``."""
+    if state.outcomes.get("implement") != Outcome.SUCCESS.value:
+        return _blocked_on_precondition(state)
+
+    stitch = state.stitch
+    if not stitch:
+        return _delegate_to_integration_test(state)
+
+    shape_issues = _diagnose_stitch(stitch)
+    if shape_issues:
+        return _blocked_on_shape(state, shape_issues)
+
+    verdict = stitch.get("verdict")
+    if verdict == "success":
+        return StepResult(outcome=Outcome.SUCCESS)
+
+    if stitch.get("integration_confirmed") is True:
+        return StepResult(
+            outcome=Outcome.SUCCESS,
+            message=(
+                f"stitch verdict `{verdict}` overridden by "
+                "integration_confirmed=True."
+            ),
+        )
+
+    return _blocked_on_bad_verdict(state, verdict, stitch)
+
+
+def _diagnose_stitch(stitch: Any) -> list[str]:
+    """Return shape errors; empty list when ``stitch`` is well-formed."""
+    if not isinstance(stitch, dict):
+        return [f"state.stitch must be a dict, got {type(stitch).__name__}"]
+    verdict = stitch.get("verdict")
+    if verdict not in _ALLOWED_VERDICTS:
+        return [
+            f"state.stitch['verdict'] must be one of "
+            f"{', '.join(_ALLOWED_VERDICTS)}; got {verdict!r}",
+        ]
+    return []
+
+
+def _preview_input(state: DeliveryState) -> str:
+    """One-line preview of the original input for halt bodies."""
+    data = state.ticket or {}
+    raw = data.get("raw")
+    if isinstance(raw, str) and raw.strip():
+        text = " ".join(raw.split())
+    else:
+        title = data.get("title")
+        text = title if isinstance(title, str) else (data.get("id") or "(no title)")
+    if len(text) <= 80:
+        return text
+    return text[:79].rstrip() + "\u2026"
+
+
+def _blocked_on_precondition(state: DeliveryState) -> StepResult:
+    """BLOCKED halt — upstream UI step did not succeed."""
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            "> Mixed `stitch` step gated on the UI step; "
+            "the implement outcome is not success.",
+            "> 1. Re-run \u2014 restart the mixed flow from the start",
+            "> 2. Abort \u2014 drop this request",
+        ],
+        message="stitch step gated on implement; upstream UI outcome is not success.",
+    )
+
+
+def _delegate_to_integration_test(state: DeliveryState) -> StepResult:
+    """Halt with an agent directive so the orchestrator runs smokes."""
+    preview = _preview_input(state)
+    contract = state.contract if isinstance(state.contract, dict) else {}
+    api_surface = contract.get("api_surface") or []
+    endpoint_count = len(api_surface) if isinstance(api_surface, list) else 0
+
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive(INTEGRATION_TEST_DIRECTIVE),
+            f"> Input: {preview}",
+            "> UI track finished; the contract / UI seam needs end-to-end "
+            "verification before the delivery report:",
+            f"> - Endpoints / actions to smoke: {endpoint_count}",
+            "> Scenarios cover the full round-trip \u2014 fill form \u2192 "
+            "server validation \u2192 response \u2192 UI update. Unit-level "
+            "passes from the UI review do **not** substitute for this gate.",
+            "> 1. Continue \u2014 run `integration-test` now",
+            "> 2. Abort \u2014 skip integration verification (NOT recommended)",
+        ],
+        message="Mixed UI complete; delegating to integration-test for stitch.",
+    )
+
+
+def _blocked_on_shape(state: DeliveryState, issues: list[str]) -> StepResult:
+    """BLOCKED halt — recorded stitch verdict is malformed."""
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            "> Recorded stitch output is malformed: "
+            + "; ".join(issues)
+            + ".",
+            "> 1. Re-run `integration-test` and resume",
+            "> 2. Abort \u2014 stitch verdict cannot be trusted",
+        ],
+        message=f"Mixed stitch shape invalid: {'; '.join(issues)}.",
+    )
+
+
+def _blocked_on_bad_verdict(
+    state: DeliveryState,
+    verdict: Any,
+    stitch: dict[str, Any],
+) -> StepResult:
+    """BLOCKED halt — verdict is blocked / partial and not user-confirmed."""
+    scenarios = stitch.get("scenarios") or []
+    scenario_count = len(scenarios) if isinstance(scenarios, list) else 0
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            f"> `integration-test` reported `{verdict}` after running "
+            f"{scenario_count} scenario(s). The delivery report cannot "
+            "claim completion on a non-success integration verdict.",
+            "> 1. Address the findings and re-run `integration-test`",
+            "> 2. Override \u2014 set `state.stitch.integration_confirmed=true` "
+            "and resume (rare; document why)",
+            "> 3. Abort",
+        ],
+        message=(
+            f"Mixed stitch verdict was `{verdict}`, not success; "
+            "user override required to continue."
+        ),
+    )
+
+
+__all__ = [
+    "AMBIGUITIES",
+    "INTEGRATION_TEST_DIRECTIVE",
+    "run",
+]