@event4u/agent-config 1.18.0 → 1.20.0

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,110 @@
+"""``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
+visibility marker.
+
+Fires on ``before_save``: ``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",
+]

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

@@ -0,0 +1,125 @@
+"""Producer-side helpers for the memory-visibility line.
+
+Implements the v1 line shape from
+``docs/contracts/memory-visibility-v1.md``:
+
+    🧠 Memory: <hits>/<asks> · ids=[<comma-separated-ids>]
+
+The semantics matched to the work-engine model:
+
+* The ``memory`` step retrieves across the four allowed memory types
+  (``MEMORY_TYPES`` in ``directives.backend.memory``). Each type is
+  one ``ask`` from the visibility-line perspective.
+* ``hits`` counts distinct types that returned at least one entry.
+* ``ids`` is the deduped list of returned entry ids preserving the
+  retrieval order encoded in ``state.memory``.
+
+Privacy floor: this module never emits entry bodies, summaries,
+``path``/``source`` fields, or anything beyond ``id`` and ``type``.
+The privacy regression test (``tests/contracts/test_memory_
+visibility_redaction.py``) keeps this guarantee enforced.
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+ICON = "\U0001F9E0"  # 🧠
+DEFAULT_MAX_INLINE_IDS = 5
+DEFAULT_ASKED_TYPES = (
+    "domain-invariants",
+    "architecture-decisions",
+    "incident-learnings",
+    "historical-patterns",
+)
+
+
+def summarise_visibility(
+    memory: Any,
+    *,
+    asked_types: Iterable[str] = DEFAULT_ASKED_TYPES,
+) -> dict[str, Any]:
+    """Reduce ``state.memory`` into the visibility-line slice.
+
+    ``memory`` is the list of hit dicts produced by
+    ``directives.backend.memory``. Returns ``{"asks", "hits", "ids"}``
+    with privacy-safe values only.
+    """
+    asked = tuple(asked_types)
+    if not memory or not isinstance(memory, list):
+        return {"asks": 0, "hits": 0, "ids": []}
+    asks = len(asked)
+    seen_types: set[str] = set()
+    ids: list[str] = []
+    seen_ids: set[str] = set()
+    for entry in memory:
+        if not isinstance(entry, dict):
+            continue
+        type_value = entry.get("type")
+        if isinstance(type_value, str):
+            seen_types.add(type_value)
+        entry_id = entry.get("id") or entry.get("rule_id")
+        if not isinstance(entry_id, (str, int)):
+            continue
+        sid = str(entry_id)
+        if sid in seen_ids:
+            continue
+        seen_ids.add(sid)
+        ids.append(sid)
+    hits = len(seen_types) if seen_types else (1 if ids else 0)
+    return {"asks": asks, "hits": hits, "ids": ids}
+
+
+def format_line(
+    summary: dict[str, Any],
+    *,
+    max_inline_ids: int = DEFAULT_MAX_INLINE_IDS,
+) -> str | None:
+    """Render the visibility line; return ``None`` when ``asks == 0``.
+
+    Cap inline ids at ``max_inline_ids`` and append ``…+N`` when the
+    list is longer. Returning ``None`` enforces the contract clause
+    "If ``asks == 0``, the engine MUST suppress the line entirely".
+    """
+    asks = int(summary.get("asks", 0) or 0)
+    if asks <= 0:
+        return None
+    hits = int(summary.get("hits", 0) or 0)
+    raw_ids = summary.get("ids") or []
+    ids = [str(i) for i in raw_ids if isinstance(i, (str, int))]
+    if max_inline_ids < 0:
+        max_inline_ids = 0
+    inline = ids[:max_inline_ids]
+    overflow = len(ids) - len(inline)
+    rendered_ids = ", ".join(inline)
+    if overflow > 0:
+        suffix = ", " if rendered_ids else ""
+        rendered_ids = f"{rendered_ids}{suffix}\u2026+{overflow}"
+    return f"{ICON} Memory: {hits}/{asks} \u00b7 ids=[{rendered_ids}]"
+
+
+def should_emit(
+    summary: dict[str, Any],
+    *,
+    cost_profile: str = "standard",
+    visibility_off: bool = False,
+) -> bool:
+    """Apply the cadence + opt-out gates from the contract."""
+    if visibility_off:
+        return False
+    asks = int(summary.get("asks", 0) or 0)
+    if asks <= 0:
+        return False
+    profile = (cost_profile or "standard").strip().lower()
+    if profile == "lean":
+        return asks >= 3
+    return True
+
+
+__all__ = [
+    "DEFAULT_ASKED_TYPES",
+    "DEFAULT_MAX_INLINE_IDS",
+    "ICON",
+    "format_line",
+    "should_emit",
+    "summarise_visibility",
+]

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

@@ -118,6 +118,35 @@ Do NOT use when:
 - Do NOT {anti-pattern 1}.
 - Do NOT {anti-pattern 2}.
 - Do NOT {anti-pattern 3}.
+
+<!-- SENIOR-TIER STUB BLOCKS (delete entire section if not `tier: senior`):
+  Senior-tier skills (frontmatter `tier: senior`) require four extra
+  blocks per `.agent-src.uncompressed/rules/skill-quality.md` §
+  Senior-Tier Required Structure. Mid-tier and untiered skills MUST
+  remove this section entirely. The four blocks are enforced by
+  `scripts/skill_linter.py` for `tier: senior` skills only.
+
+  ## Related Skills
+
+  **WHEN to use this**
+  - {situation A this skill resolves better than peer skill}
+  - {situation B}
+
+  **WHEN NOT to use this**
+  - {situation C} — route to [`{peer-skill}`](../{peer-skill}/SKILL.md)
+  - {situation D} — route to [`{peer-skill}`](../{peer-skill}/SKILL.md)
+
+  ## When the agent should load this
+
+  - "{user phrase 1 — concrete paraphrase}"
+  - "{user phrase 2}"
+  - "{user phrase 3}"
+
+  ## Output
+
+  1. **{artifact-name.md}** — {shape: markdown table / tree / report}
+  2. **{artifact-name-2.md}** — {shape}
+-->
 ````
 
 ## Quality Checklist (5 Skill Killers)
@@ -132,5 +161,5 @@ Before considering a skill complete, verify it passes all 5 checks:
 - [ ] **K6: Under 500 lines** — if larger, extract reference tables or templates into separate files in the skill folder
 - [ ] **English only** — all content in English
 - [ ] **No duplication** — doesn't repeat rules or guidelines that are already enforced elsewhere
-- [ ] **No "Related skills" section** — the agent discovers skills via `<available_skills>` descriptions; cross-links waste tokens and create maintenance burden
+- [ ] **No "Related skills" section for mid-tier / untiered skills** — the agent discovers them via `<available_skills>` descriptions; cross-links waste tokens. Senior-tier skills (`tier: senior`) MUST include the block per `skill-quality.md` § Senior-Tier Required Structure (linter-enforced).