@event4u/agent-config 6.1.0 → 7.0.0

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

@@ -1,254 +0,0 @@
-"""``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/dist/agent-src/templates/scripts/work_engine/directives/mixed/stitch.py

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