@event4u/agent-config 1.17.0 → 1.19.0

package/.agent-src/skills/roadmap-management/SKILL.md

@@ -117,11 +117,28 @@ Every roadmap follows this structure:
 
 ### Quality gates
 
-Every roadmap implicitly includes these gates (run after each step that changes code):
+Every roadmap implicitly includes the project's quality pipeline
+(static analysis, autofixes, tests). What's configurable is **when**
+the pipeline runs during `/roadmap execute`, controlled by
+`roadmap.quality_cadence` in `.agent-settings.yml`:
 
-- PHPStan must pass (detect command: artisan vs composer, see `rules/docker-commands.md`)
-- Rector: run with fix flag, verify no new PHPStan errors
-- Tests: run affected tests
+| Cadence | Pipeline runs | Trade-off |
+|---|---|---|
+| `end_of_roadmap` (default) | Once before archiving | Fastest, fewest tokens; errors compound across phases |
+| `per_phase` | After every completed phase + final | Balanced; catches drift at phase boundaries |
+| `per_step` | After every completed step + final | Legacy verbose; highest token cost |
+
+The default is `end_of_roadmap` because most steps are checkbox-only
+content edits and a final pipeline run is the cheapest way to satisfy
+`verify-before-complete`. Switch to `per_phase` for risky migrations or
+unfamiliar codebases.
+
+**Always-on, regardless of cadence:**
+
+- Step checkboxes flip `[ ] → [x]` and the dashboard regenerates **same
+  response** (enforced by `roadmap-progress-sync`).
+- Before any "roadmap complete" claim or archival, the pipeline runs
+  fresh (enforced by `verify-before-complete`).
 
 ### Step granularity
 
@@ -149,6 +166,14 @@ Every roadmap implicitly includes these gates (run after each step that changes
    the roadmap text. If the user declines, do **not** re-propose during
    `roadmap-execute`. Decline = silence. See [`scope-control`](../../rules/scope-control.md#decline--silence--no-re-asking-on-the-same-task).
 5. Save with a kebab-case filename (e.g. `optimize-webhook-jobs.md`).
+   **Before writing**, scan the entire roadmap namespace for a
+   collision — active, `archive/`, `skipped/`, and nested subdirs —
+   with `find agents/roadmaps -type f -iname "<name>.md"`. If any
+   hit comes back, stop and ask the user to rename, open the
+   existing file, or abort. Never silently overwrite an archived
+   or skipped roadmap. Detailed prompt in
+   [`commands/roadmap/create.md`](../../commands/roadmap/create.md)
+   step 6.
 6. Regenerate the dashboard so the new roadmap is included.
 
 ### Executing a roadmap

package/.agent-src/skills/verify-completion-evidence/SKILL.md

@@ -128,7 +128,12 @@ When reporting completion to the user:
 3. **Result** — numeric breakdown (tests passed/failed/skipped, errors,
    warnings)
 4. **Caveats** — anything the output flagged but you chose to accept
-5. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
+5. **Untracked files** — if `git status --short` shows any untracked
+   files in the working tree, list them verbatim in the report. This
+   prevents silently-shipped artefacts (logs, scratch scripts, ad-hoc
+   notes) from disappearing into a future commit. Empty list means
+   omit the section.
+6. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
 
 ## Gotchas
 
@@ -188,3 +193,5 @@ Before sending a completion message:
 * [ ] No warnings or skips are hidden
 * [ ] Targeted tests green → full suite green → quality pipeline clean
 * [ ] `git status` reflects only the intended change set
+* [ ] If `git status --short` shows untracked files, the report lists
+      them verbatim under "Untracked files"

package/.agent-src/templates/agent-settings.md

@@ -217,6 +217,21 @@ pipelines:
   # Included by every cost_profile except `custom`.
   skill_improvement: true
 
+# --- Roadmap execution ---
+#
+# Controls when /roadmap execute runs the project's quality pipeline.
+# Step checkboxes and the dashboard are ALWAYS updated in the same
+# response — that cadence is governed by `roadmap-progress-sync` and
+# is non-negotiable. This setting only governs *quality tool runs*.
+roadmap:
+  # When to run quality tools during /roadmap execute.
+  #   end_of_roadmap = once, before archiving (default — fastest, fewest tokens)
+  #   per_phase      = once after every completed phase
+  #   per_step       = after every completed step (legacy; highest token cost)
+  # Iron Law `verify-before-complete` still applies — fresh output is
+  # mandatory before any "roadmap complete" claim, regardless of cadence.
+  quality_cadence: end_of_roadmap
+
 # --- Subagent orchestration ---
 subagents:
   # Model for implementer subagents (empty = same tier as the session model)
@@ -362,6 +377,7 @@ lives under `personal:` in YAML.
 | `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the four chat-history hooks (turn-check, append, halt-append, heartbeat). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
+| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |

package/.agent-src/templates/roadmaps.md

@@ -39,11 +39,16 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
 
 ---
 
-## Quality Gates (always apply)
+## Quality Gates (always apply at completion)
 
-Every roadmap must pass these before it is considered done:
+Every roadmap must pass the project's quality pipeline before it is
+considered done. **When** the pipeline runs during `/roadmap execute` is
+governed by `roadmap.quality_cadence` in `.agent-settings.yml`
+(`end_of_roadmap` default → once before archival; `per_phase` → after
+every phase; `per_step` → after every step). Either way, a final fresh
+run is mandatory before "complete" per `verify-before-complete`.
 
-Run the project's quality pipeline and test suite. Common commands:
+Common commands:
 
 ```bash
 # PHP projects (inside Docker container if applicable)
@@ -64,6 +69,10 @@ Check `AGENTS.md` or `Makefile` / `Taskfile.yml` for the exact commands.
 Copy the structure below into a new file:
 
 ```markdown
+---
+complexity: lightweight
+---
+
 # Roadmap: {Short descriptive title}
 
 > {One sentence: What is the expected outcome?}

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -19,8 +19,10 @@ from .hooks.builtin import (
     ChatHistoryHaltAppendHook,
     ChatHistoryHeartbeatHook,
     ChatHistoryTurnCheckHook,
+    DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
 )
@@ -56,6 +58,13 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
         StateShapeValidationHook().register(registry)
     if settings.directive_set_guard:
         DirectiveSetGuardHook().register(registry)
+    if settings.decision_trace:
+        DecisionTraceHook().register(registry)
+    if settings.memory_visibility:
+        MemoryVisibilityHook(
+            cost_profile=settings.cost_profile,
+            visibility_off=settings.memory_visibility_off,
+        ).register(registry)
     if settings.chat_history_enabled:
         _register_chat_history_hooks(registry, settings)
 

package/.agent-src/templates/scripts/work_engine/hooks/__init__.py

@@ -24,8 +24,10 @@ from .builtin import (
     ChatHistoryHaltAppendHook,
     ChatHistoryHeartbeatHook,
     ChatHistoryTurnCheckHook,
+    DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
 )
@@ -40,6 +42,7 @@ __all__ = [
     "ChatHistoryHaltAppendHook",
     "ChatHistoryHeartbeatHook",
     "ChatHistoryTurnCheckHook",
+    "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
     "HookCallback",
@@ -49,6 +52,7 @@ __all__ = [
     "HookHalt",
     "HookRegistry",
     "HookRunner",
+    "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
 ]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py

@@ -15,8 +15,10 @@ from .chat_history_append import ChatHistoryAppendHook
 from .chat_history_halt_append import ChatHistoryHaltAppendHook
 from .chat_history_heartbeat import ChatHistoryHeartbeatHook
 from .chat_history_turn_check import ChatHistoryTurnCheckHook
+from .decision_trace import DecisionTraceHook
 from .directive_set_guard import DirectiveSetGuardHook
 from .halt_surface_audit import HaltSurfaceAuditHook
+from .memory_visibility import MemoryVisibilityHook
 from .state_shape_validation import StateShapeValidationHook
 from .trace import TraceHook
 
@@ -25,8 +27,10 @@ __all__ = [
     "ChatHistoryHaltAppendHook",
     "ChatHistoryHeartbeatHook",
     "ChatHistoryTurnCheckHook",
+    "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
+    "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
 ]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/decision_trace.py

@@ -0,0 +1,163 @@
+"""``DecisionTraceHook`` — emit a decision-trace JSON per phase.
+
+Implements the v1 envelope from ``docs/contracts/decision-trace-v1.md``.
+Default-off; opt-in via ``.agent-settings.yml``
+``decision_engine.surface_traces: true`` (mirrored into
+``hooks.decision_trace.enabled`` by :mod:`work_engine.hooks.settings`).
+
+The hook is purely observational — it never mutates ``DeliveryState``,
+never raises terminal errors. Stream / disk failures surface as
+:class:`HookError` (non-fatal per the three-tier contract).
+
+Trace layout (matches the contract):
+
+* ``schema_version: 1``
+* ``work_id`` — derived from the state-file directory name when the
+  caller follows the ``agents/state/work/<id>/state.json`` convention,
+  else from the state-file stem.
+* ``phase`` — engine ``step_name`` (refine/memory/.../report).
+* ``started_at`` / ``ended_at`` — ISO-8601 UTC timestamps captured on
+  ``BEFORE_STEP`` and ``AFTER_STEP``.
+* ``confidence_band`` / ``risk_class`` — heuristics defined in
+  :mod:`work_engine.scoring.decision_trace`.
+* ``rules`` — empty by default; the engine layer populates rule
+  applications when concerns wire into the trace bus (later phase).
+* ``memory`` — counts and ids snapshotted from ``state.memory``.
+* ``verify`` — claims/first-try-passes derived from ``state.verify``.
+"""
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ...scoring.decision_trace import (
+    derive_confidence_band,
+    derive_risk_class,
+    summarise_memory,
+    summarise_verify,
+)
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+
+SCHEMA_VERSION = 1
+_MAX_MEMORY_IDS = 32
+
+
+class DecisionTraceHook:
+    """Emit one decision-trace JSON file per dispatcher step.
+
+    Parameters
+    ----------
+    output_dir:
+        Optional override for the trace destination. When ``None`` the
+        hook writes alongside the WorkState file: if the state file
+        sits under ``agents/state/work/<id>/state.json`` the trace
+        lands at ``agents/state/work/<id>/decision-trace-<phase>.json``;
+        otherwise the trace lands next to the state file as
+        ``<stem>.decision-trace-<phase>.json``.
+    """
+
+    def __init__(self, output_dir: Path | None = None) -> None:
+        self._output_dir = output_dir
+        self._state_file: Path | None = None
+        self._step_started: dict[str, float] = {}
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register the trace callbacks on the lifecycle events used."""
+        registry.register(HookEvent.BEFORE_LOAD, self._capture_state_file)
+        registry.register(HookEvent.AFTER_LOAD, self._capture_state_file)
+        registry.register(HookEvent.BEFORE_STEP, self._mark_step_start)
+        registry.register(HookEvent.AFTER_STEP, self._emit_trace)
+
+    # -- lifecycle callbacks ------------------------------------------
+
+    def _capture_state_file(self, ctx: HookContext) -> None:
+        if ctx.state_file is not None:
+            self._state_file = Path(ctx.state_file)
+
+    def _mark_step_start(self, ctx: HookContext) -> None:
+        if ctx.step_name:
+            self._step_started[ctx.step_name] = time.time()
+
+    def _emit_trace(self, ctx: HookContext) -> None:
+        if not ctx.step_name:
+            return
+        started = self._step_started.pop(ctx.step_name, time.time())
+        envelope = self._build_envelope(ctx, started)
+        target = self._target_path(ctx.step_name)
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(
+                json.dumps(envelope, indent=2, sort_keys=False) + "\n",
+                encoding="utf-8",
+            )
+        except OSError as exc:
+            raise HookError(f"decision-trace write failed: {exc}") from exc
+
+    # -- envelope construction ----------------------------------------
+
+    def _build_envelope(
+        self, ctx: HookContext, started: float,
+    ) -> dict[str, Any]:
+        delivery = ctx.delivery
+        memory = summarise_memory(
+            getattr(delivery, "memory", None),
+            limit=_MAX_MEMORY_IDS,
+        )
+        verify = summarise_verify(getattr(delivery, "verify", None))
+        ambiguity = bool(getattr(delivery, "questions", None))
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "work_id": self._work_id(),
+            "phase": ctx.step_name,
+            "started_at": _iso_utc(started),
+            "ended_at": _iso_utc(time.time()),
+            "confidence_band": derive_confidence_band(
+                memory_hits=memory["hits"],
+                verify_claims=verify["claims"],
+                verify_first_try_passes=verify["first_try_passes"],
+                ambiguity_flag=ambiguity,
+            ),
+            "risk_class": derive_risk_class(
+                getattr(delivery, "changes", None),
+            ),
+            "rules": [],
+            "memory": memory,
+            "verify": verify,
+        }
+
+    # -- path helpers --------------------------------------------------
+
+    def _work_id(self) -> str:
+        if self._state_file is None:
+            return "unknown"
+        parent = self._state_file.parent
+        if parent.name and parent.parent.name == "work":
+            return parent.name
+        return self._state_file.stem
+
+    def _target_path(self, phase: str) -> Path:
+        filename = f"decision-trace-{phase}.json"
+        if self._output_dir is not None:
+            return self._output_dir / filename
+        if self._state_file is None:
+            return Path(filename)
+        parent = self._state_file.parent
+        if parent.name and parent.parent.name == "work":
+            return parent / filename
+        return parent / f"{self._state_file.stem}.{filename}"
+
+
+def _iso_utc(epoch: float) -> str:
+    return (
+        datetime.fromtimestamp(epoch, tz=timezone.utc)
+        .strftime("%Y-%m-%dT%H:%M:%SZ")
+    )
+
+
+__all__ = ["DecisionTraceHook", "SCHEMA_VERSION"]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/memory_visibility.py

@@ -0,0 +1,111 @@
+"""``MemoryVisibilityHook`` — emit the visibility line on save.
+
+Implements the producer side of
+``docs/contracts/memory-visibility-v1.md``: derive ``asks/hits/ids``
+from ``state.memory`` and thread the rendered line into
+``state.report`` so the agent's reply naturally carries the memory
+heartbeat.
+
+Fires on ``before_save`` for the same reason as
+``ChatHistoryHeartbeatHook``: ``cli._sync_back`` runs between
+``after_dispatch`` and ``before_save`` and reassigns
+``work.report = delivery.report``. A line written on
+``after_dispatch`` would be overwritten before ``_save``; firing on
+``before_save`` lands after the sync.
+
+Default-off; opt-in via ``.agent-settings.yml``
+``hooks.memory_visibility.enabled: true`` (or implicitly when
+``memory.visibility`` is not ``off`` and the master switch is on).
+The hook is purely observational: failures surface as
+:class:`HookError` (non-fatal per the three-tier contract); the
+engine never crashes on a visibility-line write.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+from ...scoring.memory_visibility import (
+    DEFAULT_ASKED_TYPES,
+    format_line,
+    should_emit,
+    summarise_visibility,
+)
+from ..context import HookContext
+from ..events import HookEvent
+from ..exceptions import HookError
+from ..registry import HookRegistry
+
+
+class MemoryVisibilityHook:
+    """Thread the ``🧠 Memory: <hits>/<asks> · ids=[…]`` line into the report.
+
+    Parameters
+    ----------
+    cost_profile:
+        Cadence profile from ``.agent-settings.yml`` (``lean`` /
+        ``standard`` / ``verbose``). ``lean`` suppresses the line
+        unless ``asks ≥ 3`` per the contract's cadence table.
+    visibility_off:
+        When ``True``, the hook stays silent — used to mirror
+        ``memory.visibility: off`` in the consumer settings.
+    asked_types:
+        Optional override for the list of memory types treated as
+        ``asks`` in the visibility line. Defaults to the four types
+        the engine's memory step retrieves over.
+    """
+
+    def __init__(
+        self,
+        *,
+        cost_profile: str = "standard",
+        visibility_off: bool = False,
+        asked_types: Iterable[str] | None = None,
+    ) -> None:
+        self._cost_profile = cost_profile
+        self._visibility_off = visibility_off
+        self._asked_types = (
+            tuple(asked_types) if asked_types is not None else DEFAULT_ASKED_TYPES
+        )
+
+    def register(self, registry: HookRegistry) -> None:
+        """Register the visibility-line emitter on ``before_save``."""
+        registry.register(HookEvent.BEFORE_SAVE, self._on_before_save)
+
+    def _on_before_save(self, ctx: HookContext) -> None:
+        work = ctx.work
+        if work is None:
+            return
+        memory = getattr(work, "memory", None)
+        summary = summarise_visibility(memory, asked_types=self._asked_types)
+        if not should_emit(
+            summary,
+            cost_profile=self._cost_profile,
+            visibility_off=self._visibility_off,
+        ):
+            return
+        line = format_line(summary)
+        if not line:
+            return
+        existing = getattr(work, "report", "") or ""
+        if line in existing:
+            return
+        sep = "\n\n" if existing else ""
+        try:
+            work.report = f"{existing}{sep}{line}"
+        except AttributeError as exc:
+            raise HookError(
+                "memory-visibility: state.report not writable",
+            ) from exc
+
+
+def derive_visibility(memory: Any) -> str | None:
+    """Convenience helper: render the line directly from a memory list.
+
+    Used by external callers (CLI ad-hoc smoke tests, the audit-as-
+    memory consumer) that have a ``memory`` list but no ``HookContext``.
+    Returns ``None`` when ``asks == 0``.
+    """
+    return format_line(summarise_visibility(memory))
+
+
+__all__ = ["MemoryVisibilityHook", "derive_visibility"]

package/.agent-src/templates/scripts/work_engine/hooks/settings.py

@@ -39,6 +39,10 @@ class HookSettings:
     halt_surface_audit: bool = False
     state_shape_validation: bool = False
     directive_set_guard: bool = False
+    decision_trace: bool = False
+    memory_visibility: bool = False
+    memory_visibility_off: bool = False
+    cost_profile: str = "standard"
     chat_history_enabled: bool = False
     chat_history_script: str = DEFAULT_CHAT_HISTORY_SCRIPT
 
@@ -102,6 +106,34 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
         and _coerce_bool(global_chat.get("enabled"), False)
     )
 
+    decision_engine = data.get("decision_engine")
+    decision_trace_on = (
+        isinstance(decision_engine, dict)
+        and _coerce_bool(decision_engine.get("surface_traces"), False)
+    )
+
+    memory_section = data.get("memory")
+    visibility_off = False
+    if isinstance(memory_section, dict):
+        raw = memory_section.get("visibility")
+        if isinstance(raw, str) and raw.strip().lower() == "off":
+            visibility_off = True
+        elif isinstance(raw, bool) and raw is False:
+            visibility_off = True
+
+    memory_hooks = hooks.get("memory_visibility")
+    if isinstance(memory_hooks, dict):
+        memory_visibility_on = _coerce_bool(
+            memory_hooks.get("enabled"), True,
+        )
+    else:
+        memory_visibility_on = True
+
+    cost_profile_raw = data.get("cost_profile") or "standard"
+    cost_profile = (
+        str(cost_profile_raw).strip().lower() or "standard"
+    )
+
     return HookSettings(
         enabled=True,
         trace=_coerce_bool(hooks.get("trace"), False),
@@ -114,6 +146,10 @@ def _settings_from_raw(data: dict[str, Any]) -> HookSettings:
         directive_set_guard=_coerce_bool(
             hooks.get("directive_set_guard"), True
         ),
+        decision_trace=decision_trace_on,
+        memory_visibility=memory_visibility_on,
+        memory_visibility_off=visibility_off,
+        cost_profile=cost_profile,
         chat_history_enabled=chat_block_enabled and global_chat_on,
         chat_history_script=chat_script,
     )

package/.agent-src/templates/scripts/work_engine/scoring/decision_trace.py

@@ -0,0 +1,141 @@
+"""Confidence-band + risk-class heuristics for decision-trace v1.
+
+These heuristics back the JSON envelope emitted by
+:class:`work_engine.hooks.builtin.DecisionTraceHook`. They live here
+(under ``scoring/``) so the rules and the hook share a single source
+of truth, and so unit tests can exercise the heuristics without
+spinning up a dispatcher.
+
+Confidence-band heuristic (per
+``docs/contracts/decision-trace-v1.md``):
+
+* ``high``   — ``memory.hits ≥ 2`` AND
+  ``verify.first_try_passes == verify.claims`` AND no ambiguity flag.
+* ``medium`` — ``memory.hits ≥ 1`` OR ``verify.first_try_passes ≥ 1``.
+* ``low``    — otherwise.
+
+Edge case: ``verify.claims == 0`` is **not** ``high`` by default; it
+folds into ``medium`` if at least one memory hit landed, ``low``
+otherwise.
+
+Risk-class heuristic: maximum risk across the files the phase
+touched. With no file-ownership matrix wired in yet, the
+implementation defaults to ``low`` and exposes a ``files`` argument
+so a future hook can pass concrete paths. If the phase touched any
+files at all the heuristic returns ``medium`` so reviewers stay
+nudged toward a closer look until the matrix lands.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+BAND_HIGH = "high"
+BAND_MEDIUM = "medium"
+BAND_LOW = "low"
+
+RISK_HIGH = "high"
+RISK_MEDIUM = "medium"
+RISK_LOW = "low"
+
+
+def derive_confidence_band(
+    *,
+    memory_hits: int,
+    verify_claims: int,
+    verify_first_try_passes: int,
+    ambiguity_flag: bool,
+) -> str:
+    """Return ``high`` / ``medium`` / ``low`` per the v1 heuristic."""
+    if (
+        memory_hits >= 2
+        and verify_claims > 0
+        and verify_first_try_passes == verify_claims
+        and not ambiguity_flag
+    ):
+        return BAND_HIGH
+    if memory_hits >= 1 or verify_first_try_passes >= 1:
+        return BAND_MEDIUM
+    return BAND_LOW
+
+
+def derive_risk_class(changes: Any) -> str:
+    """Return the trace-level risk class.
+
+    ``changes`` is the ``delivery.changes`` slice — a list of dicts in
+    the canonical engine shape, or ``None`` for pure planning phases.
+    Until the file-ownership matrix is wired in, "any change touched"
+    maps to ``medium``; "no change" maps to ``low``. ``high`` is
+    reserved for the future ownership-matrix lookup.
+    """
+    if not changes:
+        return RISK_LOW
+    if isinstance(changes, Iterable):
+        try:
+            count = sum(1 for _ in changes)
+        except TypeError:
+            return RISK_LOW
+        return RISK_MEDIUM if count > 0 else RISK_LOW
+    return RISK_LOW
+
+
+def summarise_memory(
+    memory: Any, *, limit: int = 32,
+) -> dict[str, Any]:
+    """Reduce ``state.memory`` into the trace-envelope ``memory`` slice.
+
+    The engine stores memory entries as dicts with at least an ``id``
+    or ``rule_id`` key plus arbitrary per-entry payload. The trace
+    only carries ids — bodies stay behind the privacy floor.
+    """
+    if not memory:
+        return {"asks": 0, "hits": 0, "ids": []}
+    ids: list[str] = []
+    asks = 0
+    hits = 0
+    for entry in memory:
+        if not isinstance(entry, dict):
+            continue
+        asks += int(entry.get("asks", 1) or 0) or 1
+        if entry.get("hit", True):
+            hits += 1
+            entry_id = entry.get("id") or entry.get("rule_id")
+            if entry_id and len(ids) < limit:
+                ids.append(str(entry_id))
+    return {"asks": asks, "hits": hits, "ids": ids}
+
+
+def summarise_verify(verify: Any) -> dict[str, int]:
+    """Reduce ``state.verify`` into the trace-envelope ``verify`` slice.
+
+    ``verify`` may be ``None`` (no verify run yet), a dict carrying
+    ``claims`` / ``first_try_passes``, or a list of attempt records.
+    Anything else collapses to zeros.
+    """
+    if verify is None:
+        return {"claims": 0, "first_try_passes": 0}
+    if isinstance(verify, dict):
+        claims = int(verify.get("claims", 0) or 0)
+        passes = int(verify.get("first_try_passes", 0) or 0)
+        return {"claims": claims, "first_try_passes": passes}
+    if isinstance(verify, list):
+        claims = len(verify)
+        passes = sum(
+            1 for entry in verify
+            if isinstance(entry, dict) and entry.get("first_try_pass")
+        )
+        return {"claims": claims, "first_try_passes": passes}
+    return {"claims": 0, "first_try_passes": 0}
+
+
+__all__ = [
+    "BAND_HIGH",
+    "BAND_MEDIUM",
+    "BAND_LOW",
+    "RISK_HIGH",
+    "RISK_MEDIUM",
+    "RISK_LOW",
+    "derive_confidence_band",
+    "derive_risk_class",
+    "summarise_memory",
+    "summarise_verify",
+]