@event4u/agent-config 6.0.0 → 6.1.0

package/dist/agent-src/templates/scripts/memory_report.py

@@ -34,7 +34,26 @@ MEMORY_ROOT = Path("agents/memory")
 INTAKE_ROOT = MEMORY_ROOT / "intake"
 CURATED_TYPES = (
     "ownership", "historical-patterns", "domain-invariants",
-    "architecture-decisions", "incident-learnings", "product-rules",
+    "incident-learnings", "product-rules",
+)
+
+# Role-mode marker grepped from session captures / reports / handoffs.
+# Matches `<!-- role-mode: <slug> | contract: ... -->` on any single line.
+# See guidelines/agent-infra/role-contracts.md "Structured mode markers".
+import re  # noqa: E402
+
+_MODE_MARKER_PATTERN = re.compile(
+    r"<!--\s*role-mode:\s*([a-z0-9][a-z0-9-]*)\s*\|"
+    r"\s*contract:[^>]*-->"
+)
+_MODE_SCAN_DIRS = (
+    Path("agents/sessions"),
+    Path("agents/runtime/reports"),
+    Path("agents/handoffs"),
+    Path("agents/learnings"),
+)
+_KNOWN_MODES = (
+    "developer", "reviewer", "tester", "po", "incident", "planner",
 )
 
 
@@ -132,6 +151,93 @@ def _staleness_report() -> list[dict]:
     return stale
 
 
+def _quarter_of(d: dt.date | str) -> str:
+    if isinstance(d, str):
+        try:
+            d = dt.date.fromisoformat(d[:10])
+        except ValueError:
+            return "unknown"
+    if not isinstance(d, dt.date):
+        return "unknown"
+    return f"{d.year}Q{(d.month - 1) // 3 + 1}"
+
+
+def _quarterly_stats() -> dict:
+    """Per-quarter breakdown: accepted curated entries, retired (supersede)
+    entries, and the curated-file staleness rate.
+
+    Feeds the Q2 outcome measurement for `road-to-agent-outcomes.md` /
+    `road-to-project-memory.md` Phase 5.
+    """
+    accepted: Counter = Counter()
+    for _, _, entry in _iter_curated_entries():
+        created = entry.get("created") or entry.get("last_validated")
+        if created is not None:
+            accepted[_quarter_of(created)] += 1
+    retired: Counter = Counter()
+    if INTAKE_ROOT.is_dir():
+        for jsonl in sorted(INTAKE_ROOT.glob("*.jsonl")):
+            with jsonl.open(encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        obj = json.loads(line)
+                    except ValueError:
+                        continue
+                    if obj.get("type") != "supersede":
+                        continue
+                    ts = obj.get("ts")
+                    if isinstance(ts, str):
+                        retired[_quarter_of(ts)] += 1
+    # Staleness rate = overdue / total curated entries (0..1).
+    total = sum(1 for _ in _iter_curated_entries())
+    overdue = len(_staleness_report())
+    rate = (overdue / total) if total else 0.0
+    return {
+        "accepted_by_quarter": dict(accepted),
+        "retired_by_quarter": dict(retired),
+        "staleness_rate": round(rate, 3),
+        "curated_total": total,
+        "curated_overdue": overdue,
+    }
+
+
+def _role_mode_stats() -> dict:
+    """Count structured mode markers across session/report/handoff dirs.
+
+    Feeds `road-to-role-modes` Phase 4 (contract-conformance signal)
+    and `road-to-curated-self-improvement` Phase 3 (outcome measurement).
+    Missing directories are silently skipped — the repo may not have
+    session captures yet.
+    """
+    counts: Counter[str] = Counter()
+    files_scanned = 0
+    unknown_modes: set[str] = set()
+    for root in _MODE_SCAN_DIRS:
+        if not root.exists():
+            continue
+        for md in root.rglob("*.md"):
+            try:
+                text = md.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                continue
+            files_scanned += 1
+            for match in _MODE_MARKER_PATTERN.finditer(text):
+                slug = match.group(1).lower()
+                counts[slug] += 1
+                if slug not in _KNOWN_MODES:
+                    unknown_modes.add(slug)
+    total = sum(counts.values())
+    return {
+        "total_markers": total,
+        "files_scanned": files_scanned,
+        "by_mode": dict(counts),
+        "unknown_modes": sorted(unknown_modes),
+    }
+
+
 def build_report() -> dict:
     status = memory_status.status()
     return {
@@ -139,10 +245,11 @@ def build_report() -> dict:
             "status": status.status,
             "backend": status.backend,
             "reason": status.reason,
-            "cli_path": status.cli_path,
         },
         "intake": _intake_stats(),
         "staleness": _staleness_report(),
+        "quarterly": _quarterly_stats(),
+        "role_modes": _role_mode_stats(),
     }
 
 
@@ -166,6 +273,29 @@ def _print_text(report: dict) -> None:
                   f"+{row['overdue_days']}d  {row['file']}")
         if len(stale) > 5:
             print(f"  (+{len(stale) - 5} more)")
+    q = report["quarterly"]
+    print(f"Quarterly: staleness-rate={q['staleness_rate']:.1%} "
+          f"({q['curated_overdue']}/{q['curated_total']})")
+    if q["accepted_by_quarter"]:
+        acc = ", ".join(f"{k}:{v}" for k, v in
+                        sorted(q["accepted_by_quarter"].items()))
+        print(f"  accepted: {acc}")
+    if q["retired_by_quarter"]:
+        ret = ", ".join(f"{k}:{v}" for k, v in
+                        sorted(q["retired_by_quarter"].items()))
+        print(f"  retired:  {ret}")
+    rm = report.get("role_modes") or {}
+    if rm.get("files_scanned"):
+        total = rm.get("total_markers", 0)
+        print(f"Role modes: {total} marker(s) in "
+              f"{rm['files_scanned']} file(s)")
+        if rm.get("by_mode"):
+            modes = ", ".join(f"{k}:{v}" for k, v in
+                              sorted(rm["by_mode"].items()))
+            print(f"  by mode: {modes}")
+        if rm.get("unknown_modes"):
+            print(f"  unknown: {', '.join(rm['unknown_modes'])} "
+                  "(not in the six reserved slugs)")
 
 
 def main() -> int:

package/dist/agent-src/templates/scripts/memory_signal.py

@@ -2,10 +2,10 @@
 """Write-side helper: drop an engineering-memory signal.
 
 Shared by producers (`/bug-fix`, `/do-and-judge`, `/propose-memory`,
-incident role exit). Routes to the optional `agent-memory` package when
-`memory_status.status() == "present"`; otherwise appends an intake
-line under `agents/memory/intake/signals-YYYY-MM.jsonl` — append-only
-JSONL with `merge=union` (see `road-to-memory-merge-safety.md`).
+incident role exit). Appends an intake line under
+`agents/memory/intake/signals-YYYY-MM.jsonl` — append-only JSONL with
+`merge=union` (see `road-to-memory-merge-safety.md`). Memory is entirely
+file-backed (no external backend).
 
 Rate limiting:
 - Per-path, per-type, within a rolling window (default 7 days).
@@ -31,12 +31,12 @@ from pathlib import Path
 from typing import Any
 
 INTAKE_ROOT = Path("agents/memory/intake")
+SETTINGS_FILE = Path(".agent-settings.yml")
 VALID_TYPES = {
     "historical-patterns",
     "incident-learnings",
     "ownership",
     "domain-invariants",
-    "architecture-decisions",
     "product-rules",
 }
 RATE_LIMIT_WINDOW_DAYS = 7
@@ -99,10 +99,8 @@ def emit(entry_type: str, path: str, body: str,
          force: bool = False) -> dict[str, Any] | None:
     """Append a signal entry. Returns the written record, or None when skipped.
 
-    On `present` backend, routing to the package is a no-op here today —
-    the package adapter is wired in `road-to-agent-memory-integration.md`
-    Phase 3. For now, the file path is the single source of truth so
-    merge-safety is preserved in every mode.
+    The intake JSONL file is the single source of truth — memory is
+    entirely file-backed (no external backend).
     """
     if entry_type not in VALID_TYPES:
         raise ValueError(f"unknown memory type: {entry_type}")

package/dist/agent-src/templates/scripts/memory_status.py

@@ -1,46 +1,27 @@
 #!/usr/bin/env python3
-"""Detect the agent-memory backend.
+"""File-backed memory status (no external backend).
 
-Single source of truth for whether skills should use the file fallback
-(`scripts/memory_lookup.py`) or route through the optional
-`@event4u/agent-memory` package.
-
-Exit codes / statuses:
-
-  * `absent`        — package not installed or CLI not on PATH
-  * `misconfigured` — installed but `health()` fails within the timeout
-  * `present`       — installed, healthy, usable now
-
-Result is cached per process under `os.environ["AGENT_MEMORY_STATUS"]`
-and (optionally) under `.agent-memory/status.cache` per session.
+The optional `@event4u/agent-memory` package was removed; retrieval
+(`scripts/memory_lookup.py`) and signal-writing (`scripts/memory_signal.py`)
+are entirely file-backed now. `status()` / `health()` report the file
+backend so the v1 retrieval-contract health envelope stays stable for
+consumers (e.g. the MCP `memory_status` tool).
 
 Usage:
     python3 scripts/memory_status.py                 # human-readable line
     python3 scripts/memory_status.py --format json   # stable JSON
-    from scripts.memory_status import status         # Python import
+    python3 scripts/memory_status.py --health        # v1 health envelope
+    from scripts.memory_status import status, health # Python import
 """
 
 from __future__ import annotations
 
 import argparse
 import json
-import os
-import shutil
-import subprocess
 import sys
-import time
 from dataclasses import dataclass, asdict
-from pathlib import Path
-from typing import Literal
 
-Status = Literal["absent", "misconfigured", "present"]
-
-_CLI_CANDIDATES = ("memory", "agent-memory", "agentmem")
-_HEALTH_TIMEOUT_SECONDS = 2.0
-_CACHE_ENV = "AGENT_MEMORY_STATUS"
-_CACHE_FILE = Path(".agent-memory") / "status.cache"
-
-# Retrieval contract version served by the file-backed fallback.
+# Retrieval contract version served by the file-backed backend.
 # Source of truth: internal/schemas/retrieval-v1.schema.json.
 CONTRACT_VERSION = 1
 _FILE_BACKEND_VERSION = "0.0.0-file"
@@ -49,184 +30,24 @@ _FILE_BACKEND_FEATURES = ("file-fallback",)
 
 @dataclass
 class Result:
-    status: Status
-    backend: str            # "file" or "package"
-    reason: str             # short explanation
-    elapsed_ms: int         # time spent probing (0 if cached)
-    cli_path: str = ""      # resolved CLI path, if any
-    # Populated only when status == "present" — sourced from the
-    # `health` CLI envelope so the v1 health() reports real package
-    # capabilities instead of file-fallback placeholders.
-    backend_version: str = ""
-    features: tuple = ()
-
-
-def _find_cli() -> str:
-    for name in _CLI_CANDIDATES:
-        path = shutil.which(name)
-        if path:
-            return path
-    return ""
-
-
-def _parse_health_envelope(stdout: str) -> dict | None:
-    """Extract the v1 health envelope from `memory health` stdout.
-
-    The package emits a single JSON object on stdout (pino structured
-    logs go to stderr). We tolerate older builds that may have leaked
-    log lines into stdout by scanning for the first top-level object
-    that carries ``contract_version``.
-    """
-    text = (stdout or "").strip()
-    if not text:
-        return None
-    try:
-        obj = json.loads(text)
-    except ValueError:
-        obj = None
-    if isinstance(obj, dict) and obj.get("contract_version"):
-        return obj
-    # Fallback: line-by-line scan for an envelope-shaped object — covers
-    # the case where structured logs accidentally share stdout.
-    for line in text.splitlines():
-        line = line.strip()
-        if not line.startswith("{"):
-            continue
-        try:
-            cand = json.loads(line)
-        except ValueError:
-            continue
-        if isinstance(cand, dict) and cand.get("contract_version"):
-            return cand
-    return None
-
-
-def _probe_health(cli_path: str) -> tuple[bool, str, dict | None]:
-    """Returns (healthy, reason, envelope).
-
-    On success ``envelope`` is the parsed v1 health envelope (may still
-    be ``None`` for very old CLIs that don't emit one). On failure it
-    is always ``None``.
-    """
-    try:
-        out = subprocess.run(
-            [cli_path, "health"],
-            capture_output=True, text=True,
-            timeout=_HEALTH_TIMEOUT_SECONDS,
-        )
-    except subprocess.TimeoutExpired:
-        return False, f"health() timed out after {_HEALTH_TIMEOUT_SECONDS}s", None
-    except FileNotFoundError:
-        return False, "CLI vanished between which() and invoke", None
-    if out.returncode != 0:
-        # First line of combined output, capped, for the reason field.
-        msg = (out.stderr or out.stdout or "exit != 0").strip().splitlines()
-        head = msg[0][:120] if msg else "exit != 0"
-        return False, f"health() returned {out.returncode}: {head}", None
-    envelope = _parse_health_envelope(out.stdout)
-    return True, "ok", envelope
-
-
-def _read_cache() -> Result | None:
-    cached = os.environ.get(_CACHE_ENV)
-    if cached:
-        try:
-            data = json.loads(cached)
-            return Result(**data)
-        except (ValueError, TypeError):
-            pass
-    if _CACHE_FILE.is_file():
-        try:
-            data = json.loads(_CACHE_FILE.read_text(encoding="utf-8"))
-            return Result(**data)
-        except (OSError, ValueError, TypeError):
-            pass
-    return None
-
-
-def _write_cache(result: Result) -> None:
-    payload = json.dumps(asdict(result))
-    os.environ[_CACHE_ENV] = payload
-    try:
-        _CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
-        _CACHE_FILE.write_text(payload, encoding="utf-8")
-    except OSError:
-        # Best-effort cache; skills MUST still work without it.
-        pass
+    status: str = "file"     # always "file" — no external backend
+    backend: str = "file"
+    reason: str = "file-backed memory (no external backend)"
+    elapsed_ms: int = 0
 
 
 def status(refresh: bool = False) -> Result:
-    """Return the cached or freshly-probed backend status.
-
-    Always returns in well under ``_HEALTH_TIMEOUT_SECONDS`` seconds on
-    cache hit; bounded by the timeout on cache miss. Never raises —
-    probe failures degrade to ``absent`` / ``misconfigured`` rather than
-    surfacing exceptions.
-    """
-    if not refresh:
-        cached = _read_cache()
-        if cached is not None:
-            cached.elapsed_ms = 0
-            return cached
-    t0 = time.monotonic()
-    cli = _find_cli()
-    if not cli:
-        result = Result("absent", "file",
-                        "agent-memory CLI not on PATH", 0)
-    else:
-        healthy, reason, envelope = _probe_health(cli)
-        elapsed = int((time.monotonic() - t0) * 1000)
-        if healthy:
-            backend_version = ""
-            features: tuple = ()
-            if isinstance(envelope, dict):
-                bv = envelope.get("backend_version")
-                if isinstance(bv, str):
-                    backend_version = bv
-                feats = envelope.get("features")
-                if isinstance(feats, list) and all(
-                    isinstance(f, str) for f in feats
-                ):
-                    features = tuple(feats)
-            result = Result("present", "package", reason, elapsed, cli,
-                            backend_version=backend_version,
-                            features=features)
-        else:
-            result = Result("misconfigured", "file", reason, elapsed, cli)
-    _write_cache(result)
-    return result
+    """Return the (constant) file-backend status. Never raises."""
+    return Result()
 
 
 def health(refresh: bool = False) -> dict:
-    """Return a v1 retrieval-contract health envelope.
-
-    Schema: ``internal/schemas/retrieval-v1.schema.json`` (HealthResponse).
-    Maps the three-state :func:`status` result onto the contract's
-    ``ok | degraded | error`` so consumers can read
-    ``contract_version`` without caring about the file-vs-package split.
-
-    When the package backs the call (``status == "present"``), the
-    envelope reports the package's own ``backend_version`` and
-    ``features`` so consumers can feature-detect against real
-    capabilities. Otherwise the file-fallback markers are returned.
-    """
-    r = status(refresh=refresh)
-    envelope_status = {
-        "present": "ok",
-        "misconfigured": "degraded",
-        "absent": "ok",
-    }[r.status]
-    if r.status == "present" and (r.backend_version or r.features):
-        backend_version = r.backend_version or _FILE_BACKEND_VERSION
-        features = list(r.features) if r.features else list(_FILE_BACKEND_FEATURES)
-    else:
-        backend_version = _FILE_BACKEND_VERSION
-        features = list(_FILE_BACKEND_FEATURES)
+    """Return a v1 retrieval-contract health envelope (file backend)."""
     return {
         "contract_version": CONTRACT_VERSION,
-        "status": envelope_status,
-        "backend_version": backend_version,
-        "features": features,
+        "status": "ok",
+        "backend_version": _FILE_BACKEND_VERSION,
+        "features": list(_FILE_BACKEND_FEATURES),
     }
 
 
@@ -234,22 +55,20 @@ def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__)
     ap.add_argument("--format", choices=["text", "json"], default="text")
     ap.add_argument("--refresh", action="store_true",
-                    help="Bypass the session cache and probe fresh")
+                    help="No-op (kept for back-compat); status is constant")
     ap.add_argument("--health", action="store_true",
                     help="Emit a v1 retrieval-contract health envelope "
-                         "instead of the legacy status line")
+                         "instead of the status line")
     args = ap.parse_args()
     if args.health:
-        print(json.dumps(health(refresh=args.refresh)))
+        print(json.dumps(health()))
         return 0
-    r = status(refresh=args.refresh)
+    r = status()
     if args.format == "json":
         print(json.dumps(asdict(r)))
     else:
-        icon = {"present": "✅", "misconfigured": "⚠️", "absent": "ℹ️"}[r.status]
-        print(f"  {icon}  backend={r.backend}  status={r.status}  "
-              f"elapsed={r.elapsed_ms}ms  reason={r.reason}")
-    # `absent` is a valid operational state, not a failure.
+        print(f"  ℹ️  backend={r.backend}  status={r.status}  "
+              f"reason={r.reason}")
     return 0
 
 

package/dist/agent-src/templates/scripts/work_engine/directives/backend/memory.py

@@ -1,11 +1,12 @@
-"""``memory`` step — bounded retrieval over the four allowed types.
+"""``memory`` step — bounded retrieval over the three allowed types.
 
 Contract (see
 ``docs/contracts/implement-ticket-flow.md#memory-retrieval-contract``):
 
-- Four allowed types: ``domain-invariants``, ``architecture-decisions``,
-  ``incident-learnings``, ``historical-patterns``.
-- Hard cap of **12** hits total across the four types.
+- Three allowed types: ``domain-invariants``, ``incident-learnings``,
+  ``historical-patterns``. (Architectural rationale lives in ADRs —
+  ``docs/decisions/`` — not in curated memory.)
+- Hard cap of **12** hits total across the three types.
 - Keys derive from the ticket — title tokens plus acceptance-criterion
   tokens plus any already-known ``files`` hint. Tokenisation is
   deliberately naive (whitespace split, lower-cased) so the retrieval
@@ -27,11 +28,10 @@ from ...delivery_state import DeliveryState, Outcome, StepResult
 
 MEMORY_TYPES: tuple[str, ...] = (
     "domain-invariants",
-    "architecture-decisions",
     "incident-learnings",
     "historical-patterns",
 )
-"""The four types allowed by the flow contract. No aliases, no extras."""
+"""The three types allowed by the flow contract. No aliases, no extras."""
 
 MAX_HITS: int = 12
 """Hard cap per the roadmap — never raise without amending the contract."""

package/dist/agent-src/templates/scripts/work_engine/directives/ui/_passthrough.py

@@ -4,9 +4,9 @@ Phase 6 of ``agents/roadmaps/road-to-product-ui-track.md`` retired the
 Phase 3 deferral stub once design / apply / review / polish landed. Two
 slots remain semantically empty for the UI track:
 
-- ``memory`` — the UI track does not consult the four memory types the
-  backend retrieves over (``domain-invariants``, ``architecture-decisions``,
-  ``incident-learnings``, ``historical-patterns``). UI work pivots on the
+- ``memory`` — the UI track does not consult the memory types the
+  backend retrieves over (``domain-invariants``, ``incident-learnings``,
+  ``historical-patterns``). UI work pivots on the
   audit findings in ``state.ui_audit`` instead, which the audit gate has
   already populated by the time this handler runs.
 - ``plan`` — :mod:`.design` produces the locked design brief that

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

@@ -35,7 +35,6 @@ ICON = "\U0001F9E0"  # 🧠
 DEFAULT_MAX_INLINE_IDS = 5
 DEFAULT_ASKED_TYPES = (
     "domain-invariants",
-    "architecture-decisions",
     "incident-learnings",
     "historical-patterns",
 )