@event4u/agent-config 1.13.0 → 1.14.0

package/.agent-src/templates/scripts/implement_ticket/__init__.py

@@ -1,40 +1,77 @@
-"""/implement-ticket orchestrator — linear step dispatcher.
-
-Shipped to consumer projects via the installer. Consumer code imports
-``DeliveryState``, ``dispatch``, and the ``Outcome`` enum from this
-package; step implementations land in Phase 2 under
-``.agent-src.uncompressed/skills/implement-ticket/`` and plug into the
-``Step`` protocol exposed here.
-
-Architectural constraints (from
-``agents/contexts/adr-implement-ticket-runtime.md`` and
-``agents/contexts/implement-ticket-flow.md``):
-
-- Runtime is Python 3.10+.
-- The dispatcher is linear, not a DAG. Eight fixed steps, fixed order.
-- ``DeliveryState`` is the only object shared between steps — no
-  hidden state, no side channels.
-- Every step terminates in ``success | blocked | partial``. ``blocked``
-  and ``partial`` halt the flow and surface numbered questions.
-- The dispatcher never calls git, writes commits, or opens PRs.
+"""``implement_ticket`` — deprecated shim, retained for one release.
+
+The engine moved to :mod:`work_engine` in R1 Phase 3. This module
+re-exports the public surface so existing imports keep working, but
+emits :class:`DeprecationWarning` on import. The Golden-Transcript
+freeze-guard pins ``./agent-config implement-ticket`` against the
+locked baseline; the shim keeps that path byte-stable while internal
+callers migrate to ``work_engine``.
+
+Remove after the next public release of this package.
 """
 from __future__ import annotations
 
-from .delivery_state import (
+import sys as _sys
+import warnings as _warnings
+
+_warnings.warn(
+    "implement_ticket has moved to work_engine; importing implement_ticket "
+    "is deprecated and will be removed in a future release. Update imports "
+    "to `from work_engine import …`.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+# Register submodule aliases so `from implement_ticket.steps.plan import …`
+# and friends keep resolving to the work_engine implementation. The legacy
+# package no longer ships these submodules on disk; sys.modules entries
+# keep dotted-path imports working until the shim is removed.
+import work_engine as _we_pkg  # noqa: E402
+import work_engine.cli as _we_cli  # noqa: E402
+import work_engine.delivery_state as _we_delivery_state  # noqa: E402
+import work_engine.dispatcher as _we_dispatcher  # noqa: E402
+import work_engine.persona_policy as _we_persona_policy  # noqa: E402
+import work_engine.directives.backend as _we_steps  # noqa: E402
+from work_engine.directives.backend import (  # noqa: E402
+    analyze as _we_step_analyze,
+    implement as _we_step_implement,
+    memory as _we_step_memory,
+    plan as _we_step_plan,
+    refine as _we_step_refine,
+    report as _we_step_report,
+    test as _we_step_test,
+    verify as _we_step_verify,
+)
+
+_sys.modules.setdefault("implement_ticket.cli", _we_cli)
+_sys.modules.setdefault("implement_ticket.delivery_state", _we_delivery_state)
+_sys.modules.setdefault("implement_ticket.dispatcher", _we_dispatcher)
+_sys.modules.setdefault("implement_ticket.persona_policy", _we_persona_policy)
+_sys.modules.setdefault("implement_ticket.steps", _we_steps)
+_sys.modules.setdefault("implement_ticket.steps.analyze", _we_step_analyze)
+_sys.modules.setdefault("implement_ticket.steps.implement", _we_step_implement)
+_sys.modules.setdefault("implement_ticket.steps.memory", _we_step_memory)
+_sys.modules.setdefault("implement_ticket.steps.plan", _we_step_plan)
+_sys.modules.setdefault("implement_ticket.steps.refine", _we_step_refine)
+_sys.modules.setdefault("implement_ticket.steps.report", _we_step_report)
+_sys.modules.setdefault("implement_ticket.steps.test", _we_step_test)
+_sys.modules.setdefault("implement_ticket.steps.verify", _we_step_verify)
+
+from work_engine import (  # noqa: E402,F401  — re-export for backwards compat
     AGENT_DIRECTIVE_PREFIX,
+    DEFAULT_PERSONA,
+    DEFAULT_STATE_FILE,
     DeliveryState,
     Outcome,
+    PersonaPolicy,
+    STEP_ORDER,
     Step,
     StepResult,
     agent_directive,
+    dispatch,
     is_agent_directive,
-)
-from .cli import DEFAULT_STATE_FILE, main
-from .dispatcher import STEP_ORDER, dispatch
-from .persona_policy import (
-    DEFAULT_PERSONA,
-    PersonaPolicy,
     known_personas,
+    main,
     resolve_policy,
 )
 

package/.agent-src/templates/scripts/implement_ticket/__main__.py

@@ -1,9 +1,15 @@
-"""Module entry point — lets ``python3 -m implement_ticket`` run the CLI."""
+"""Deprecated CLI entry point — delegates to :mod:`work_engine`.
+
+``python3 -m implement_ticket`` still works because the Golden-Transcript
+freeze-guard pins that invocation. Internally it forwards to
+``work_engine.cli.main`` after emitting a ``DeprecationWarning`` from
+the package ``__init__``.
+"""
 from __future__ import annotations
 
 import sys
 
-from .cli import main
+from work_engine.cli import main
 
 if __name__ == "__main__":
     sys.exit(main())

package/.agent-src/templates/scripts/telemetry/__init__.py

@@ -0,0 +1,42 @@
+"""``telemetry`` — artefact engagement recording (default-off).
+
+The package owns the local-only engagement log
+(``.agent-engagement.jsonl``) that records, at task boundaries, which
+artefacts (skills, rules, commands, guidelines, personas) the agent
+``consulted`` (loaded into context) and ``applied`` (cited or directly
+drove a decision).
+
+Architectural constraints (from
+``agents/roadmaps/road-to-artifact-engagement-telemetry.md`` Phase 1):
+
+- Default-off. ``telemetry.artifact_engagement.enabled: false`` in
+  ``.agent-settings.yml`` produces zero file IO and zero token cost.
+- Local only. No server-side aggregation, no cross-repo sync.
+- ID-only payloads. No paths, no file contents, no prompts, no
+  secrets ever reach the log.
+- Append-only JSONL. One event per task / phase-step boundary.
+- Strict schema. Unknown artefact kinds are rejected.
+"""
+from __future__ import annotations
+
+from .engagement import (
+    ALLOWED_BOUNDARY_KINDS,
+    ALLOWED_KINDS,
+    SCHEMA_VERSION,
+    EngagementEvent,
+    EngagementSchemaError,
+    append_event,
+    now_utc_iso,
+    parse_event,
+)
+
+__all__ = [
+    "ALLOWED_BOUNDARY_KINDS",
+    "ALLOWED_KINDS",
+    "SCHEMA_VERSION",
+    "EngagementEvent",
+    "EngagementSchemaError",
+    "append_event",
+    "now_utc_iso",
+    "parse_event",
+]

package/.agent-src/templates/scripts/telemetry/aggregator.py

@@ -0,0 +1,154 @@
+"""Engagement-log aggregator (Phase 4).
+
+Pure-stdlib reader: streams ``.agent-engagement.jsonl``, groups events by
+``(kind, id)``, and returns per-artefact statistics. The renderer in
+``report_renderer.py`` consumes the dataclasses produced here.
+
+Design contract:
+
+- **Skip, don't crash.** Malformed JSONL lines are counted in
+  ``AggregateResult.skipped_lines`` and dropped. Phase 4 Step 4 locks
+  this behaviour: a single corrupt line in a 10k-line log must not
+  block the report.
+- **No IO besides the log read.** No network, no settings reads, no
+  log creation. Caller (CLI) is responsible for feeding a real path.
+- **``since`` is exclusive on the lower bound** — ``since`` of
+  ``2026-04-01T00:00:00Z`` keeps events with ``ts > since``. ``None``
+  means "include everything".
+- **Stats are sort-stable.** ``rank_artefacts`` returns a list ordered
+  by ``applied`` desc, ``consulted`` desc, then ``(kind, id)`` asc, so
+  two reports over the same log render byte-identical.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable, Iterator
+
+from .engagement import EngagementEvent, EngagementSchemaError, parse_event
+
+
+@dataclass(frozen=True)
+class ArtefactStat:
+    kind: str
+    artefact_id: str
+    consulted: int
+    applied: int
+    last_seen_ts: str
+
+    @property
+    def applied_ratio(self) -> float:
+        """Applied / consulted. ``0.0`` when never consulted (impossible
+        in practice — applied is a strict subset of consulted — but the
+        guard keeps the division safe for malformed inputs)."""
+        return (self.applied / self.consulted) if self.consulted else 0.0
+
+
+@dataclass
+class AggregateResult:
+    total_events: int = 0
+    parsed_events: int = 0
+    skipped_lines: int = 0
+    earliest_ts: str | None = None
+    latest_ts: str | None = None
+    artefacts: dict[tuple[str, str], dict[str, object]] = field(default_factory=dict)
+
+    def stats(self) -> list[ArtefactStat]:
+        """Materialise the accumulated buckets as immutable stats."""
+        out: list[ArtefactStat] = []
+        for (kind, art_id), bucket in self.artefacts.items():
+            out.append(
+                ArtefactStat(
+                    kind=kind,
+                    artefact_id=art_id,
+                    consulted=int(bucket["consulted"]),
+                    applied=int(bucket["applied"]),
+                    last_seen_ts=str(bucket["last_seen_ts"]),
+                )
+            )
+        return out
+
+
+def _parse_iso(ts: str) -> datetime | None:
+    """Parse a ``%Y-%m-%dT%H:%M:%SZ`` stamp into UTC. Returns ``None``
+    for malformed stamps so the caller can skip the comparison cleanly.
+    """
+    if not isinstance(ts, str) or not ts:
+        return None
+    try:
+        # strptime with literal Z handles the ``now_utc_iso`` format.
+        return datetime.strptime(ts, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    except ValueError:
+        return None
+
+
+def _iter_events(log_path: Path) -> Iterator[tuple[int, EngagementEvent | None]]:
+    """Yield ``(line_number, event_or_None)``. ``None`` signals a skip."""
+    if not log_path.is_file():
+        return
+    with log_path.open("r", encoding="utf-8") as fh:
+        for line_no, line in enumerate(fh, start=1):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            try:
+                event = parse_event(stripped + "\n")
+            except EngagementSchemaError:
+                yield line_no, None
+                continue
+            yield line_no, event
+
+
+def aggregate(
+    log_path: Path,
+    *,
+    since: datetime | None = None,
+) -> AggregateResult:
+    """Stream the JSONL log and compute per-artefact stats."""
+    result = AggregateResult()
+    for _line_no, event in _iter_events(log_path):
+        result.total_events += 1
+        if event is None:
+            result.skipped_lines += 1
+            continue
+        ts = _parse_iso(event.ts)
+        if since is not None and ts is not None and ts <= since:
+            continue
+        result.parsed_events += 1
+        if result.earliest_ts is None or event.ts < result.earliest_ts:
+            result.earliest_ts = event.ts
+        if result.latest_ts is None or event.ts > result.latest_ts:
+            result.latest_ts = event.ts
+        _accumulate(result.artefacts, event.consulted, event.applied, event.ts)
+    return result
+
+
+def _accumulate(
+    bucket: dict[tuple[str, str], dict[str, object]],
+    consulted: dict[str, list[str]],
+    applied: dict[str, list[str]],
+    ts: str,
+) -> None:
+    for kind, ids in consulted.items():
+        for art_id in ids:
+            entry = bucket.setdefault((kind, art_id), {"consulted": 0, "applied": 0, "last_seen_ts": ""})
+            entry["consulted"] = int(entry["consulted"]) + 1  # type: ignore[operator]
+            if ts > str(entry["last_seen_ts"]):
+                entry["last_seen_ts"] = ts
+    for kind, ids in applied.items():
+        for art_id in ids:
+            entry = bucket.setdefault((kind, art_id), {"consulted": 0, "applied": 0, "last_seen_ts": ""})
+            entry["applied"] = int(entry["applied"]) + 1  # type: ignore[operator]
+            if ts > str(entry["last_seen_ts"]):
+                entry["last_seen_ts"] = ts
+
+
+def rank_artefacts(stats: Iterable[ArtefactStat]) -> list[ArtefactStat]:
+    return sorted(
+        stats,
+        key=lambda s: (-s.applied, -s.consulted, s.kind, s.artefact_id),
+    )
+
+
+__all__ = ["ArtefactStat", "AggregateResult", "aggregate", "rank_artefacts"]

package/.agent-src/templates/scripts/telemetry/boundary.py

@@ -0,0 +1,171 @@
+"""Boundary detection + concurrent-safe recording (Phase 2).
+
+Two responsibilities, one module:
+
+1. ``BoundarySession`` — in-process coalescing. Multiple ``add_*`` calls
+   within one task / phase-step / tool-call boundary merge into a
+   single emitted event (set-union on ``consulted`` / ``applied``).
+   Idempotent: calling ``flush()`` twice without new additions is a
+   no-op; calling ``add_consulted("skills", ["x"])`` twice records
+   ``"x"`` once.
+
+2. ``record_event`` — cross-process durability. Uses ``fcntl.flock``
+   (POSIX) so concurrent writers from separate ``./agent-config
+   telemetry:record`` invocations cannot interleave inside one JSONL
+   line. On non-POSIX (no ``fcntl``) we fall back to a best-effort
+   append; the package only ships on POSIX-compatible CI today.
+
+The CLI in ``cli.py`` is the only caller that should touch the log
+path directly. Agent-side flows wire through ``BoundarySession``.
+"""
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterable, Iterator
+
+try:  # POSIX advisory file locking
+    import fcntl  # type: ignore[import-not-found]
+    _HAS_FCNTL = True
+except ImportError:  # pragma: no cover — Windows / sandbox
+    _HAS_FCNTL = False
+
+from .engagement import (
+    ALLOWED_BOUNDARY_KINDS,
+    ALLOWED_KINDS,
+    EngagementEvent,
+    EngagementSchemaError,
+    now_utc_iso,
+)
+
+
+@dataclass
+class BoundarySession:
+    """Collect artefact engagements for one boundary, flush once.
+
+    Use as a context manager — ``__exit__`` flushes on clean exit and
+    suppresses on exception (so failed tasks don't pollute the log).
+    """
+
+    task_id: str
+    boundary_kind: str
+    log_path: Path
+    consulted: dict[str, set[str]] = field(default_factory=dict)
+    applied: dict[str, set[str]] = field(default_factory=dict)
+    _flushed: bool = False
+    _has_data: bool = False
+
+    def __post_init__(self) -> None:
+        if self.boundary_kind not in ALLOWED_BOUNDARY_KINDS:
+            raise EngagementSchemaError(
+                f"boundary_kind must be one of {ALLOWED_BOUNDARY_KINDS!r}"
+            )
+        if not isinstance(self.task_id, str) or not self.task_id:
+            raise EngagementSchemaError("task_id must be a non-empty string")
+
+    def add_consulted(self, kind: str, ids: Iterable[str]) -> None:
+        self._merge(self.consulted, kind, ids)
+
+    def add_applied(self, kind: str, ids: Iterable[str]) -> None:
+        self._merge(self.applied, kind, ids)
+
+    def _merge(self, bucket: dict[str, set[str]], kind: str, ids: Iterable[str]) -> None:
+        if kind not in ALLOWED_KINDS:
+            raise EngagementSchemaError(
+                f"{kind!r} is not an allowed artefact kind "
+                f"(allowed: {ALLOWED_KINDS!r})"
+            )
+        target = bucket.setdefault(kind, set())
+        for art_id in ids:
+            if not isinstance(art_id, str) or not art_id:
+                raise EngagementSchemaError(
+                    f"{kind} ids must be non-empty strings"
+                )
+            target.add(art_id)
+            self._has_data = True
+
+    def to_event(self) -> EngagementEvent:
+        return EngagementEvent(
+            ts=now_utc_iso(),
+            task_id=self.task_id,
+            boundary_kind=self.boundary_kind,
+            consulted={k: sorted(v) for k, v in self.consulted.items() if v},
+            applied={k: sorted(v) for k, v in self.applied.items() if v},
+        )
+
+    def flush(self) -> bool:
+        """Write one merged event to the log. Returns True if written.
+
+        No-op when already flushed or no data was added — keeps the
+        boundary idempotent.
+        """
+        if self._flushed or not self._has_data:
+            return False
+        record_event(self.log_path, self.to_event())
+        self._flushed = True
+        return True
+
+    def __enter__(self) -> "BoundarySession":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        if exc_type is None:
+            self.flush()
+        # On exception: do nothing — failed boundary, no record.
+
+
+def record_event(log_path: Path, event: EngagementEvent) -> None:
+    """Append one event under an exclusive file lock.
+
+    The lock guarantees that two concurrent writers append two
+    complete, well-formed lines instead of one interleaved line. We
+    open with ``"a"`` so each write atomically extends EOF on POSIX
+    once the lock is held.
+    """
+    event.validate()
+    payload = event.to_jsonl().encode("utf-8")
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(log_path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o644)
+    try:
+        if _HAS_FCNTL:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        try:
+            written = 0
+            while written < len(payload):
+                written += os.write(fd, payload[written:])
+            os.fsync(fd)
+        finally:
+            if _HAS_FCNTL:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+    finally:
+        os.close(fd)
+
+
+@contextmanager
+def open_boundary(
+    task_id: str,
+    boundary_kind: str,
+    log_path: Path,
+) -> Iterator[BoundarySession]:
+    """Convenience context manager around ``BoundarySession``.
+
+    >>> with open_boundary("ticket-1", "task", Path(".agent-engagement.jsonl")) as s:
+    ...     s.add_consulted("skills", ["php-coder"])
+    ...     s.add_applied("skills", ["php-coder"])
+    """
+    session = BoundarySession(
+        task_id=task_id,
+        boundary_kind=boundary_kind,
+        log_path=log_path,
+    )
+    with session:
+        yield session
+
+
+__all__ = [
+    "BoundarySession",
+    "open_boundary",
+    "record_event",
+]