@event4u/agent-config 1.9.1

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

@@ -0,0 +1,195 @@
+"""``report`` step — delivery report renderer.
+
+Produces the markdown block described in
+``agents/contexts/implement-ticket-flow.md#delivery-report-schema``.
+All nine headings are present on every run — the schema is stable
+for consumers — but section bodies are omitted when the matching
+slice of ``DeliveryState`` is empty. The single exception is the
+**Memory that mattered** section, which per contract is dropped
+entirely (heading included) when no hit carries a
+``changed_outcome`` marker.
+
+The step is pure and deterministic: no I/O, no subprocess, no
+randomness. It reads ``DeliveryState``, writes ``state.report``,
+and always returns ``SUCCESS``.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from ..delivery_state import DeliveryState, Outcome, StepResult
+from ..persona_policy import resolve_policy
+
+AMBIGUITIES: tuple[dict[str, str], ...] = ()
+"""Report rendering is pure and always succeeds — no blocked paths."""
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Render the delivery report into ``state.report`` and return SUCCESS."""
+    state.report = _render(state)
+    return StepResult(outcome=Outcome.SUCCESS)
+
+
+def _render(state: DeliveryState) -> str:
+    sections = [
+        _ticket_section(state),
+        _persona_section(state),
+        _plan_section(state),
+        _changes_section(state),
+        _tests_section(state),
+        _verify_section(state),
+        _memory_section(state),
+        _followups_section(state),
+        _next_commands_section(state),
+    ]
+    # Drop sections that opted out (memory-that-mattered returns "" when no
+    # hit influenced an outcome — per the report schema drop-rule).
+    return "\n\n".join(section for section in sections if section)
+
+
+def _ticket_section(state: DeliveryState) -> str:
+    ticket = state.ticket or {}
+    ticket_id = ticket.get("id") or "(no id)"
+    title = ticket.get("title") or "(no title)"
+    return f"## Ticket\n\n{ticket_id} — {title}"
+
+
+def _persona_section(state: DeliveryState) -> str:
+    return f"## Persona\n\n{state.persona or '(unset)'}"
+
+
+def _plan_section(state: DeliveryState) -> str:
+    body = _format_plan(state.plan)
+    return "## Plan\n\n" + (body or "_(no plan recorded)_")
+
+
+def _format_plan(plan: Any) -> str:
+    """Render whatever shape ``state.plan`` carries.
+
+    Accepts a list of step strings, a list of ``{title, detail}`` dicts,
+    or a single string — the contract doc intentionally leaves the
+    plan shape loose until ``feature-plan`` wiring lands in a later
+    phase.
+    """
+    if not plan:
+        return ""
+    if isinstance(plan, str):
+        return plan.strip()
+    if isinstance(plan, list):
+        lines = []
+        for idx, item in enumerate(plan, start=1):
+            if isinstance(item, dict):
+                title = item.get("title") or item.get("step") or f"Step {idx}"
+                detail = item.get("detail") or item.get("note") or ""
+                lines.append(
+                    f"{idx}. **{title}**" + (f" — {detail}" if detail else ""),
+                )
+            else:
+                lines.append(f"{idx}. {item}")
+        return "\n".join(lines)
+    # Last resort: string-coerce an unknown shape so the renderer never
+    # crashes on experimental plan structures.
+    return str(plan)
+
+
+def _changes_section(state: DeliveryState) -> str:
+    if not state.changes:
+        return "## Changes\n\n_(no file changes recorded)_"
+    lines = ["## Changes", ""]
+    for change in state.changes:
+        path = change.get("path") or change.get("file") or "(unknown file)"
+        lines_range = change.get("lines") or change.get("range") or ""
+        purpose = change.get("purpose") or change.get("why") or ""
+        prefix = f"- `{path}`"
+        if lines_range:
+            prefix += f" ({lines_range})"
+        if purpose:
+            prefix += f" — {purpose}"
+        lines.append(prefix)
+    return "\n".join(lines)
+
+
+def _tests_section(state: DeliveryState) -> str:
+    return "## Tests\n\n" + _format_kv_block(state.tests, "_(no tests ran)_")
+
+
+def _verify_section(state: DeliveryState) -> str:
+    return "## Verify\n\n" + _format_kv_block(state.verify, "_(no verify verdict)_")
+
+
+def _memory_section(state: DeliveryState) -> str:
+    """Render **only** hits that changed an outcome (per report schema)."""
+    influential = [
+        hit for hit in (state.memory or [])
+        if isinstance(hit, dict) and hit.get("changed_outcome")
+    ]
+    if not influential:
+        return ""  # drop the whole section — heading included
+    lines = ["## Memory that mattered", ""]
+    for hit in influential:
+        hit_id = hit.get("id") or "(no id)"
+        hit_type = hit.get("type") or "(no type)"
+        note = hit.get("note") or hit.get("why") or ""
+        suffix = f" — {note}" if note else ""
+        lines.append(f"- `{hit_id}` ({hit_type}){suffix}")
+    return "\n".join(lines)
+
+
+def _followups_section(state: DeliveryState) -> str:
+    followups = _extract_followups(state)
+    if not followups:
+        return "## Follow-ups\n\n_(none)_"
+    lines = ["## Follow-ups", ""]
+    for item in followups:
+        anchor = item.get("anchor") or ""
+        note = item.get("note") or item.get("title") or "(untitled)"
+        prefix = f"- {note}"
+        if anchor:
+            prefix += f" — `{anchor}`"
+        lines.append(prefix)
+    return "\n".join(lines)
+
+
+def _extract_followups(state: DeliveryState) -> list[dict[str, Any]]:
+    """Follow-ups may live on any slice; aggregate them in reading order."""
+    collected: list[dict[str, Any]] = []
+    for source in (state.plan, state.verify, state.tests):
+        if isinstance(source, dict):
+            for item in source.get("followups") or []:
+                if isinstance(item, dict):
+                    collected.append(item)
+    return collected
+
+
+def _next_commands_section(state: DeliveryState) -> str:
+    if not resolve_policy(state.persona).suggests_next_commands:
+        # Advisory personas produce a plan-only report; suggesting a
+        # commit or PR would mislead the reader — nothing was changed.
+        return ""
+    commands = _suggest_commands(state)
+    lines = ["## Suggested next commands", ""]
+    lines.extend(f"- `{cmd}`" for cmd in commands)
+    return "\n".join(lines)
+
+
+def _suggest_commands(state: DeliveryState) -> list[str]:
+    """Always suggest ``/commit`` and ``/create-pr`` when verify was successful."""
+    if state.outcomes.get("verify") == Outcome.SUCCESS.value:
+        return ["/commit", "/create-pr"]
+    return ["/commit"]
+
+
+def _format_kv_block(value: Any, empty_placeholder: str) -> str:
+    """Render a dict-ish slice as a bullet list; fall back to placeholder."""
+    if not value:
+        return empty_placeholder
+    if isinstance(value, dict):
+        return "\n".join(_render_kv_lines(value.items()))
+    if isinstance(value, str):
+        return value.strip() or empty_placeholder
+    return str(value)
+
+
+def _render_kv_lines(pairs: Iterable[tuple[str, Any]]) -> list[str]:
+    """Render ``(key, value)`` pairs as one Markdown bullet per pair."""
+    return [f"- **{key}:** {value}" for key, value in pairs]

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

@@ -0,0 +1,180 @@
+"""``test`` step — gate + Option-A delegation for running the test suite.
+
+The dispatcher never spawns subprocesses. Test execution is handed
+to the agent via ``@agent-directive: run-tests scope=targeted``; the
+agent drives the project's test runner (pytest, Pest, phpunit, …),
+captures the verdict onto ``state.tests``, marks
+``outcomes['test'] = 'success'``, and re-invokes the dispatcher.
+
+Contract for ``state.tests`` when populated:
+
+- Must be a dict.
+- Must carry a ``verdict`` key \u2014 one of ``success``, ``failed``,
+  or ``mixed`` (targeted vs full-suite split). Anything else blocks.
+- ``failed`` or ``mixed`` verdicts halt with the verdict as part of
+  the surfaced message so the user decides whether to continue or
+  stop. This follows the ``verify-before-complete`` rule: a bad test
+  outcome must never be silently skipped.
+- Optional keys (``targeted``, ``full``, ``duration_ms``,
+  ``followups``) 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
+
+_ALLOWED_VERDICTS = ("success", "failed", "mixed")
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "upstream_implement_failed",
+        "trigger": "`implement` outcome is not `success`",
+        "resolution": "re-run `/implement-ticket` from the start",
+    },
+    {
+        "code": "empty_tests_delegate",
+        "trigger": "`state.tests` empty — test runner not invoked yet",
+        "resolution": (
+            "agent directive `run-tests scope=targeted|full` → "
+            "`/tests-execute` (qa persona widens to full suite)"
+        ),
+    },
+    {
+        "code": "malformed_tests",
+        "trigger": (
+            "`state.tests` is not a dict or `verdict` is not one of "
+            "success / failed / mixed"
+        ),
+        "resolution": "re-run tests and record a clean verdict",
+    },
+    {
+        "code": "bad_test_verdict",
+        "trigger": "`state.tests['verdict']` is `failed` or `mixed`",
+        "resolution": "fix failures and re-run, or abort",
+    },
+)
+"""Declared ambiguity surfaces. Advisory personas skip this step entirely."""
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Gate on ``implement``, then either delegate or validate ``state.tests``."""
+    policy = resolve_policy(state.persona)
+    if not policy.allows_test:
+        return StepResult(
+            outcome=Outcome.SUCCESS,
+            message=f"test skipped: persona `{policy.name}` is plan-only.",
+        )
+
+    if state.outcomes.get("implement") != Outcome.SUCCESS.value:
+        return _blocked_on_precondition(state)
+
+    tests = state.tests
+    if not tests:
+        return _delegate_to_run_tests(state, policy.widen_tests)
+
+    shape_issues = _diagnose_tests(tests)
+    if shape_issues:
+        return _blocked_on_shape(state, shape_issues)
+
+    # At this point ``tests`` is a dict with a recognised verdict.
+    verdict = tests.get("verdict")
+    if verdict != "success":
+        return _blocked_on_bad_verdict(state, verdict)
+
+    return StepResult(outcome=Outcome.SUCCESS)
+
+
+def _diagnose_tests(tests: Any) -> list[str]:
+    if not isinstance(tests, dict):
+        return [f"state.tests must be a dict, got {type(tests).__name__}"]
+    verdict = tests.get("verdict")
+    if verdict not in _ALLOWED_VERDICTS:
+        return [
+            f"state.tests['verdict'] must be one of "
+            f"{', '.join(_ALLOWED_VERDICTS)}; got {verdict!r}",
+        ]
+    return []
+
+
+def _delegate_to_run_tests(state: DeliveryState, widen: bool) -> StepResult:
+    """Emit the ``run-tests`` directive.
+
+    ``widen`` comes from the persona policy (``qa`` widens to the full
+    suite). The directive scope becomes the first thing an orchestrator
+    reads, so the widened case is visible without parsing the options.
+    """
+    ticket_id = (state.ticket or {}).get("id") or "(no id)"
+    scope = "full" if widen else "targeted"
+    description = (
+        "full suite (qa persona widens to catch regressions outside "
+        "the changed paths)"
+        if widen
+        else "targeted first (`--filter` on the changed paths), full "
+        "suite only if targeted passes"
+    )
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive("run-tests", ticket=ticket_id, scope=scope),
+            f"> Ticket {ticket_id} \u2014 running tests: {description}.",
+            f"> 1. Continue \u2014 run {scope} tests now",
+            "> 2. Abort \u2014 skip testing (NOT recommended)",
+        ],
+        message=f"Ticket {ticket_id} needs its tests run before verification.",
+    )
+
+
+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 test gate refused: "
+            "`implement` step did not complete successfully.",
+            "> 1. Re-run `/implement-ticket` from the start",
+            "> 2. Abort",
+        ],
+        message=(
+            f"Ticket {ticket_id} cannot test: implement 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 test output is malformed: "
+            + "; ".join(issues)
+            + ".",
+            "> 1. Re-run tests and resume",
+            "> 2. Abort \u2014 test verdict cannot be trusted",
+        ],
+        message=f"Ticket {ticket_id} tests shape invalid: {'; '.join(issues)}.",
+    )
+
+
+def _blocked_on_bad_verdict(state: DeliveryState, verdict: Any) -> StepResult:
+    ticket_id = (state.ticket or {}).get("id") or "(no id)"
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            f"> Ticket {ticket_id} \u2014 tests reported `{verdict}`. "
+            "Verification cannot proceed on a non-success verdict.",
+            "> 1. Fix the failing tests and re-run `run-tests`",
+            "> 2. Continue anyway \u2014 override (NOT recommended)",
+            "> 3. Abort",
+        ],
+        message=f"Ticket {ticket_id} test verdict was `{verdict}`, not success.",
+    )
+
+
+__all__ = ["AMBIGUITIES", "run"]

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

@@ -0,0 +1,170 @@
+"""``verify`` step — gate + Option-A delegation to ``review-changes``.
+
+The dispatcher does not run the review-changes judges itself; the
+agent invokes the composite review (bug-hunter + security +
+test-coverage + code-quality) and captures the consolidated
+verdict onto ``state.verify``.
+
+``state.verify`` contract when populated:
+
+- Must be a dict.
+- Must carry a ``verdict`` key — one of ``success``, ``blocked``,
+  ``partial``. Matches the ``Outcome`` vocabulary used everywhere
+  else in the flow.
+- A ``success`` verdict advances the flow to ``report``.
+- A ``blocked`` or ``partial`` verdict halts with numbered options
+  so the user decides whether to address the findings, override
+  (rarely appropriate), or abort.
+- Optional keys (``confidence``, ``findings``, ``followups``) 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
+
+_ALLOWED_VERDICTS = ("success", "blocked", "partial")
+
+AMBIGUITIES: tuple[dict[str, str], ...] = (
+    {
+        "code": "upstream_test_failed",
+        "trigger": "`test` outcome is not `success`",
+        "resolution": "re-run `/implement-ticket` from the start",
+    },
+    {
+        "code": "empty_verify_delegate",
+        "trigger": "`state.verify` empty — four-judge review not run yet",
+        "resolution": "agent directive `review-changes` → `/review-changes`",
+    },
+    {
+        "code": "malformed_verify",
+        "trigger": (
+            "`state.verify` is not a dict or `verdict` is not one of "
+            "success / blocked / partial"
+        ),
+        "resolution": "re-run `/review-changes` and record a clean verdict",
+    },
+    {
+        "code": "bad_verify_verdict",
+        "trigger": "`state.verify['verdict']` is `blocked` or `partial`",
+        "resolution": (
+            "address findings and re-run `/review-changes` — never bypass "
+            "(see `verify-before-complete`)"
+        ),
+    },
+)
+"""Declared ambiguity surfaces. Advisory personas skip this step entirely."""
+
+
+def run(state: DeliveryState) -> StepResult:
+    """Gate on ``test``, then either delegate or validate ``state.verify``."""
+    policy = resolve_policy(state.persona)
+    if not policy.allows_verify:
+        return StepResult(
+            outcome=Outcome.SUCCESS,
+            message=f"verify skipped: persona `{policy.name}` is plan-only.",
+        )
+
+    if state.outcomes.get("test") != Outcome.SUCCESS.value:
+        return _blocked_on_precondition(state)
+
+    verify = state.verify
+    if not verify:
+        return _delegate_to_review_changes(state)
+
+    shape_issues = _diagnose_verify(verify)
+    if shape_issues:
+        return _blocked_on_shape(state, shape_issues)
+
+    verdict = verify.get("verdict")
+    if verdict != "success":
+        return _blocked_on_bad_verdict(state, verdict)
+
+    return StepResult(outcome=Outcome.SUCCESS)
+
+
+def _diagnose_verify(verify: Any) -> list[str]:
+    if not isinstance(verify, dict):
+        return [f"state.verify must be a dict, got {type(verify).__name__}"]
+    verdict = verify.get("verdict")
+    if verdict not in _ALLOWED_VERDICTS:
+        return [
+            f"state.verify['verdict'] must be one of "
+            f"{', '.join(_ALLOWED_VERDICTS)}; got {verdict!r}",
+        ]
+    return []
+
+
+def _delegate_to_review_changes(state: DeliveryState) -> StepResult:
+    ticket_id = (state.ticket or {}).get("id") or "(no id)"
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            agent_directive("review-changes", ticket=ticket_id),
+            f"> Ticket {ticket_id} \u2014 running the four-judge review "
+            "(bugs, security, tests, code quality) before the delivery "
+            "report is written.",
+            "> 1. Continue \u2014 run `review-changes` now",
+            "> 2. Abort \u2014 skip review (NOT recommended)",
+        ],
+        message=(
+            f"Ticket {ticket_id} needs `review-changes` before the report."
+        ),
+    )
+
+
+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 verify gate refused: "
+            "`test` step did not complete successfully.",
+            "> 1. Re-run `/implement-ticket` from the start",
+            "> 2. Abort",
+        ],
+        message=f"Ticket {ticket_id} cannot verify: test 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 verify output is malformed: "
+            + "; ".join(issues)
+            + ".",
+            "> 1. Re-run `review-changes` and resume",
+            "> 2. Abort \u2014 verify verdict cannot be trusted",
+        ],
+        message=f"Ticket {ticket_id} verify shape invalid: {'; '.join(issues)}.",
+    )
+
+
+def _blocked_on_bad_verdict(state: DeliveryState, verdict: Any) -> StepResult:
+    ticket_id = (state.ticket or {}).get("id") or "(no id)"
+    return StepResult(
+        outcome=Outcome.BLOCKED,
+        questions=[
+            f"> Ticket {ticket_id} \u2014 `review-changes` reported "
+            f"`{verdict}`. The delivery report cannot claim completion on a "
+            "non-success verdict (see `verify-before-complete`).",
+            "> 1. Address the findings and re-run `review-changes`",
+            "> 2. Continue anyway \u2014 override (NOT recommended)",
+            "> 3. Abort",
+        ],
+        message=(
+            f"Ticket {ticket_id} verify verdict was `{verdict}`, not success."
+        ),
+    )
+
+
+__all__ = ["AMBIGUITIES", "run"]

package/.agent-src/templates/scripts/memory_hash.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Content-addressed hash for a curated memory entry.
+
+The hash is SHA-256 over the canonical-JSON-serialized entry, truncated
+to the first 12 hex chars. Canonical JSON sorts object keys, uses no
+extra whitespace, and normalises types so two equivalent entries hash
+identically regardless of YAML formatting.
+
+Used by `/memory-promote` to pick the filename
+`agents/memory/<type>/<hash>.yml` so the same entry promoted on two
+branches converges to a single file after `git merge`.
+
+Usage:
+    python3 scripts/memory_hash.py --yaml path/to/entry.yml
+    echo '{"id":"x"}' | python3 scripts/memory_hash.py --json-stdin
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+HASH_LEN = 12
+
+
+def canonical_json(obj: Any) -> bytes:
+    return json.dumps(
+        obj,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        default=str,
+    ).encode("utf-8")
+
+
+def hash_entry(obj: Any) -> str:
+    return hashlib.sha256(canonical_json(obj)).hexdigest()[:HASH_LEN]
+
+
+def _load_yaml(path: Path) -> Any:
+    try:
+        import yaml
+    except ImportError:
+        print("error: PyYAML not installed. `pip install pyyaml`.",
+              file=sys.stderr)
+        sys.exit(2)
+    with path.open(encoding="utf-8") as fh:
+        return yaml.safe_load(fh)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    grp = ap.add_mutually_exclusive_group(required=True)
+    grp.add_argument("--yaml", help="YAML file containing one entry")
+    grp.add_argument("--json-stdin", action="store_true",
+                     help="Read JSON object from stdin")
+    args = ap.parse_args()
+    if args.yaml:
+        entry = _load_yaml(Path(args.yaml))
+    else:
+        entry = json.load(sys.stdin)
+    if not isinstance(entry, (dict, list)):
+        print(f"error: expected object/array, got {type(entry).__name__}",
+              file=sys.stderr)
+        return 1
+    print(hash_entry(entry))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())