@event4u/agent-config 1.13.0 → 1.14.0

package/.agent-src/templates/scripts/work_engine/directives/ui_trivial/apply.py

@@ -0,0 +1,165 @@
+"""``apply`` step — single-file edit path for the ``ui-trivial`` set.
+
+Phase 2 Step 6 of ``agents/roadmaps/road-to-product-ui-track.md``: the
+short-circuit path for micro UI edits that provably cannot warrant the
+full audit / design / review / polish loop. Hard preconditions enforced
+on every rebound:
+
+- edit surface **≤ 1 file**
+- **≤ 5 changed lines**
+- **no new component**
+- **no new state** (no new Livewire props, React hooks, Vue refs)
+- **no new dependency** (no Composer/npm package added)
+
+Any precondition violation BLOCKS with an ``@agent-directive:
+reclassify-to-ui-improve`` halt; the orchestrator promotes
+``state.directive_set`` to ``"ui-improve"`` (the audit-gated path) and
+re-invokes the engine. The audit gate is **not** weakened — it is
+bypassed only for cases that mathematically cannot need it.
+
+On first pass ``state.ticket["trivial_edit"]`` is unset; the step
+delegates to the agent via ``@agent-directive: trivial-apply``. The
+agent inspects the request, performs the edit, and writes the envelope
+back so the rebound runs the deterministic checks.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...delivery_state import (
+    DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+)
+
+MAX_FILES: int = 1
+"""Edit-surface ceiling — single-file edits only."""
+
+MAX_LINES_CHANGED: int = 5
+"""Changed-line ceiling — anything larger is structural, not trivial."""
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "trivial_envelope_missing",
+        "trigger": "state.ticket['trivial_edit'] unset — first pass",
+        "resolution": "agent directive `trivial-apply` → agent performs "
+        "the single-file edit and writes the envelope back",
+    },
+    {
+        "code": "trivial_preconditions_violated",
+        "trigger": "edit touches >1 file, >5 lines, adds component/state/dependency",
+        "resolution": "agent directive `reclassify-to-ui-improve` → "
+        "orchestrator promotes directive_set='ui-improve' and re-runs "
+        "through the full audit gate",
+    },
+)
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Apply the trivial-edit gate."""
+    envelope = _trivial_envelope(state)
+    if envelope is None:
+        return _delegate_to_agent(state)
+
+    violations = _check_preconditions(envelope)
+    if violations:
+        return _halt_reclassify(state, violations)
+
+    _record_change(state, envelope)
+    return StepResult(outcome=Outcome.SUCCESS)
+
+
+def _trivial_envelope(state: DeliveryState) -> dict[str, Any] | None:
+    """Return the agent-written ``trivial_edit`` envelope, or ``None``."""
+    data = state.ticket or {}
+    envelope = data.get("trivial_edit")
+    if isinstance(envelope, dict) and envelope:
+        return envelope
+    return None
+
+
+def _check_preconditions(envelope: dict[str, Any]) -> list[str]:
+    """Return a list of violation codes; empty when all preconditions pass."""
+    violations: list[str] = []
+
+    files = envelope.get("files")
+    if not isinstance(files, list) or len(files) == 0:
+        violations.append("files_missing")
+    elif len(files) > MAX_FILES:
+        violations.append(f"files_exceeded:{len(files)}>{MAX_FILES}")
+
+    lines = envelope.get("lines_changed")
+    try:
+        lines_int = int(lines)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        violations.append("lines_changed_missing")
+    else:
+        if lines_int > MAX_LINES_CHANGED:
+            violations.append(f"lines_exceeded:{lines_int}>{MAX_LINES_CHANGED}")
+        if lines_int < 0:
+            violations.append("lines_changed_negative")
+
+    if envelope.get("new_component"):
+        violations.append("new_component")
+    if envelope.get("new_state"):
+        violations.append("new_state")
+    if envelope.get("new_dependency"):
+        violations.append("new_dependency")
+
+    return violations
+
+
+def _delegate_to_agent(state: DeliveryState) -> StepResult:
+    """First-pass halt — delegate to the agent for the single-file edit."""
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive("trivial-apply"),
+            "> Trivial UI edit path \u2014 audit / design / review skipped.",
+            "> 1. Continue \u2014 perform the single-file edit, then "
+            "write a `trivial_edit` envelope back into state.ticket "
+            "(files, lines_changed, new_component, new_state, new_dependency)",
+            "> 2. Abort \u2014 drop this trivial edit",
+        ],
+        message="Trivial UI edit pending; delegating to agent for single-file edit.",
+    )
+
+
+def _halt_reclassify(state: DeliveryState, violations: list[str]) -> StepResult:
+    """BLOCKED halt \u2014 orchestrator must reclassify to ``ui-improve``."""
+    state.ticket["__reclassify_to__"] = "ui-improve"
+    state.ticket.pop("trivial_edit", None)
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive("reclassify-to-ui-improve"),
+            "> Trivial-edit preconditions violated; this work needs the "
+            "full audit gate.",
+            f"> Violations: {', '.join(violations)}.",
+            "> 1. Reclassify \u2014 orchestrator sets "
+            "`state.directive_set = \"ui-improve\"` and re-runs the engine",
+            "> 2. Abort \u2014 drop this UI request",
+        ],
+        message=(
+            "Trivial-edit preconditions failed "
+            f"({', '.join(violations)}); reclassification required."
+        ),
+    )
+
+
+def _record_change(state: DeliveryState, envelope: dict[str, Any]) -> None:
+    """Write a single ``state.changes`` entry summarising the trivial edit."""
+    files = envelope.get("files") or []
+    lines = envelope.get("lines_changed", 0)
+    state.changes.append(
+        {
+            "kind": "ui-trivial",
+            "files": list(files),
+            "lines_changed": lines,
+            "summary": envelope.get("summary") or "trivial UI edit",
+        },
+    )
+
+
+__all__ = ["AMBIGUITIES", "MAX_FILES", "MAX_LINES_CHANGED", "run"]

package/.agent-src/templates/scripts/work_engine/directives/ui_trivial/refine.py

@@ -0,0 +1,66 @@
+"""``refine`` step — intent gate for the ``ui-trivial`` directive set.
+
+Phase 2 Step 6 of ``agents/roadmaps/road-to-product-ui-track.md``:
+``ui-trivial`` is reachable only when Phase 1's intent classifier (or
+an explicit user override) labelled the work as ``ui-trivial``. Reaching
+this slot through any other route is a routing error, not a user-facing
+ambiguity.
+
+The handler is deterministic and tiny: confirm the ticket carries the
+expected intent label (or accept the default when ``directive_set`` is
+already pinned), and return ``SUCCESS``. The hard safety floor lives at
+the ``implement`` slot (``apply.py``); the audit-bypass decision is
+re-validated there against the actual edit surface, not the prompt.
+"""
+from __future__ import annotations
+
+from ...delivery_state import DeliveryState, Outcome, StepResult
+
+EXPECTED_INTENT: str = "ui-trivial"
+"""Intent label that gates entry into this directive set."""
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "wrong_intent_for_trivial",
+        "trigger": (
+            "state.ticket['intent'] is set and not equal to 'ui-trivial' "
+            "— routing landed on this set by mistake"
+        ),
+        "resolution": (
+            "abort and re-run with the correct directive_set "
+            "(populate_routing should select 'ui' or 'backend' instead)"
+        ),
+    },
+)
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Confirm the ticket's intent matches the trivial path.
+
+    The ticket's ``intent`` is optional on v0 callers; absence is
+    treated as a silent pass since the v0 path predates intent
+    classification. v1 callers always carry an intent — a mismatch
+    means the dispatcher routed incorrectly and we halt loudly so
+    the wiring bug surfaces before any edit happens.
+    """
+    intent = (state.ticket or {}).get("intent")
+    if intent is None or intent == EXPECTED_INTENT:
+        return StepResult(outcome=Outcome.SUCCESS)
+
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            "> Routing error \u2014 the ``ui-trivial`` directive set was "
+            f"selected but the ticket's intent is `{intent}`.",
+            "> 1. Reclassify \u2014 set `state.directive_set` from the "
+            "intent label and re-invoke the engine",
+            "> 2. Abort \u2014 drop this run",
+        ],
+        message=(
+            f"intent={intent!r} but directive_set='ui-trivial'; "
+            "routing must be reclassified before any edit"
+        ),
+    )
+
+
+__all__ = ["AMBIGUITIES", "EXPECTED_INTENT", "run"]

package/.agent-src/templates/scripts/work_engine/directives/ui_trivial/report.py

@@ -0,0 +1,62 @@
+"""``report`` step — one-line delivery summary for the trivial path.
+
+Phase 2 Step 6 of ``agents/roadmaps/road-to-product-ui-track.md``:
+"Trivial path emits a one-line delivery summary, not the full report."
+
+Rationale: the full backend report has nine sections — overkill for a
+single-file, ≤5-line edit. The trivial summary captures what the
+operator needs to see: which file, how many lines, what the edit did,
+and the smoke verdict. Anything richer means the work was not
+trivial, in which case ``apply`` should have reclassified to
+``ui-improve`` and run the full UI track instead.
+
+The step is pure and deterministic: reads :class:`DeliveryState`,
+writes ``state.report``, always returns ``SUCCESS``.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...delivery_state import DeliveryState, Outcome, StepResult
+
+AMBIGUITIES: tuple[dict[str, str], ...] = ()
+"""Pure render \u2014 no blocked paths."""
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Render the one-line trivial summary into ``state.report``."""
+    state.report = _render(state)
+    return StepResult(outcome=Outcome.SUCCESS)
+
+
+def _render(state: DeliveryState) -> str:
+    change = _last_trivial_change(state)
+    if change is None:
+        return "_(trivial UI edit \u2014 no change recorded)_"
+
+    files = change.get("files") or []
+    lines = change.get("lines_changed", 0)
+    summary = (change.get("summary") or "trivial UI edit").strip()
+    file_str = files[0] if len(files) == 1 else f"{len(files)} files"
+    verdict = _smoke_verdict(state)
+    verdict_str = f" \u2014 smoke: **{verdict}**" if verdict else ""
+    return f"**Trivial edit:** {summary} (`{file_str}`, {lines} lines){verdict_str}"
+
+
+def _last_trivial_change(state: DeliveryState) -> dict[str, Any] | None:
+    for change in reversed(state.changes or []):
+        if isinstance(change, dict) and change.get("kind") == "ui-trivial":
+            return change
+    return None
+
+
+def _smoke_verdict(state: DeliveryState) -> str:
+    tests = state.tests
+    if isinstance(tests, dict):
+        verdict = tests.get("verdict")
+        if isinstance(verdict, str):
+            return verdict
+    return ""
+
+
+__all__ = ["AMBIGUITIES", "run"]

package/.agent-src/templates/scripts/work_engine/directives/ui_trivial/test.py

@@ -0,0 +1,115 @@
+"""``test`` step — smoke-test delegate for the ``ui-trivial`` set.
+
+Phase 2 Step 6 of ``agents/roadmaps/road-to-product-ui-track.md``:
+the trivial path runs "apply + smoke-test only". Smoke scope means
+the agent runs the narrowest test layer that proves the edit didn't
+visibly break the touched surface — render-test for a Blade partial,
+unit-test for the touched component, or a single-file pytest scope —
+not the full project suite.
+
+The handler is the smaller cousin of
+:mod:`work_engine.directives.backend.test`: same verdict contract on
+``state.tests``, narrower scope on the agent directive. ``failed`` /
+``mixed`` verdicts halt with the verdict echoed back; ``success``
+flows through.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ...delivery_state import (
+    DeliveryState,
+    Outcome,
+    StepResult,
+    agent_directive,
+)
+
+_ALLOWED_VERDICTS: tuple[str, ...] = ("success", "failed", "mixed")
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "empty_tests_delegate",
+        "trigger": "`state.tests` empty \u2014 smoke runner not invoked yet",
+        "resolution": (
+            "agent directive `run-tests scope=smoke` \u2192 "
+            "`/tests-execute` (narrowest layer covering the touched file)"
+        ),
+    },
+    {
+        "code": "malformed_tests",
+        "trigger": (
+            "`state.tests` is not a dict or `verdict` is not one of "
+            "success / failed / mixed"
+        ),
+        "resolution": "re-run smoke and record a clean verdict",
+    },
+    {
+        "code": "bad_test_verdict",
+        "trigger": "`state.tests['verdict']` is `failed` or `mixed`",
+        "resolution": "fix the regression and re-run, or abort",
+    },
+)
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Gate the smoke verdict; delegate when ``state.tests`` is empty."""
+    tests = state.tests
+    if not tests:
+        return _delegate()
+
+    if not isinstance(tests, dict):
+        return _malformed(f"state.tests is {type(tests).__name__}, expected dict")
+
+    verdict = tests.get("verdict")
+    if verdict not in _ALLOWED_VERDICTS:
+        return _malformed(
+            f"state.tests['verdict']={verdict!r} not in {_ALLOWED_VERDICTS}",
+        )
+
+    if verdict == "success":
+        return StepResult(outcome=Outcome.SUCCESS)
+
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            f"> Smoke test verdict: **{verdict}** \u2014 trivial edit may "
+            "have regressed the touched surface.",
+            "> 1. Investigate \u2014 read failures, fix, re-run smoke",
+            "> 2. Reclassify \u2014 promote to `ui-improve` if the regression "
+            "indicates the edit was less trivial than assumed",
+            "> 3. Abort \u2014 revert the edit",
+        ],
+        message=f"smoke verdict={verdict} on trivial edit",
+    )
+
+
+def _delegate() -> StepResult:
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive("run-tests", scope="smoke"),
+            "> Trivial edit applied; run the smoke test layer covering "
+            "the touched file.",
+            "> 1. Continue \u2014 invoke `/tests-execute` with smoke scope, "
+            "then write the verdict back to `state.tests`",
+            "> 2. Skip \u2014 record `state.tests = {\"verdict\": \"success\", "
+            "\"scope\": \"none\"}` (logged as a deferred verification)",
+            "> 3. Abort \u2014 drop this run",
+        ],
+        message="smoke run not yet invoked",
+    )
+
+
+def _malformed(detail: str) -> StepResult:
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            f"> Malformed test envelope: {detail}.",
+            "> 1. Re-run smoke \u2014 produce a clean verdict",
+            "> 2. Abort \u2014 drop this run",
+        ],
+        message=detail,
+    )
+
+
+__all__ = ["AMBIGUITIES", "run"]