@event4u/agent-config 1.9.1

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

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+"""File-based retrieval for the `absent` path.
+
+Implements the shared `retrieve(types, keys, limit)` abstraction used
+by skills. Reads YAML under `agents/memory/<type>/` (curated, hand-
+reviewed) and JSONL under `agents/memory/intake/*.jsonl` (agent-written,
+append-only, supersede-chain aware).
+
+The returned shape is identical to the `present`-path adapter over the
+`@event4u/agent-memory` API, so skills stay backend-agnostic.
+
+Usage:
+    python3 scripts/memory_lookup.py --types domain-invariants,ownership \\
+        --key "app/Http/Controllers/Foo" --limit 5
+    python3 scripts/memory_lookup.py --types incident-learnings --format json
+
+    from scripts.memory_lookup import retrieve
+    hits = retrieve(types=["ownership"], keys=["app/Http"], limit=3)
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import sys
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+from typing import Any, Iterable
+
+MEMORY_ROOT = Path("agents/memory")
+INTAKE_ROOT = MEMORY_ROOT / "intake"
+
+CURATED_TYPES = {
+    "ownership",
+    "historical-patterns",
+    "domain-invariants",
+    "architecture-decisions",
+    "incident-learnings",
+    "product-rules",
+}
+
+
+@dataclass
+class Hit:
+    id: str
+    type: str
+    source: str            # "curated" or "intake"
+    path: str              # file that produced the hit
+    score: float           # naive, content-match based [0..1]
+    entry: dict = field(default_factory=dict)
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def _load_yaml(path: Path):
+    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) or {}
+
+
+def _iter_curated_entries(mtype: str) -> Iterable[tuple[Path, dict]]:
+    """Yield (file, entry) pairs for curated files of `mtype`.
+
+    Supports both the content-addressed layout (`agents/memory/<type>/
+    <hash>.yml` — one entry per file) and the single-file layout
+    (`agents/memory/<type>.yml` or `<type>/entries.yml` with an
+    ``entries:`` list), so consumers can adopt either.
+    """
+    type_dir = MEMORY_ROOT / mtype
+    single_file = MEMORY_ROOT / f"{mtype}.yml"
+    if single_file.is_file():
+        data = _load_yaml(single_file)
+        for e in data.get("entries") or []:
+            if isinstance(e, dict):
+                yield single_file, e
+    if type_dir.is_dir():
+        for yml in sorted(type_dir.rglob("*.yml")):
+            data = _load_yaml(yml) or {}
+            entries = data.get("entries")
+            if isinstance(entries, list):
+                for e in entries:
+                    if isinstance(e, dict):
+                        yield yml, e
+            elif isinstance(data, dict) and data.get("id"):
+                # Flat, one-entry-per-file layout (content-addressed).
+                yield yml, data
+
+
+def _iter_intake_entries(mtype: str) -> Iterable[tuple[Path, dict]]:
+    """Yield (file, entry) from intake JSONL, applying supersede chains."""
+    if not INTAKE_ROOT.is_dir():
+        return
+    # Resolve supersede chains globally per file: later lines win.
+    for jsonl in sorted(INTAKE_ROOT.glob("*.jsonl")):
+        by_id: dict[str, dict] = {}
+        superseded: set[str] = set()
+        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":
+                    target = obj.get("supersedes")
+                    if isinstance(target, str):
+                        superseded.add(target)
+                    continue
+                eid = obj.get("id")
+                if isinstance(eid, str):
+                    by_id[eid] = obj
+        for eid, obj in by_id.items():
+            if eid in superseded:
+                continue
+            if mtype and obj.get("entry_type") and obj["entry_type"] != mtype:
+                continue
+            yield jsonl, obj
+
+
+def _score(entry: dict, keys: list[str]) -> float:
+    """Naive relevance score: max over keys of (glob-match | substring).
+
+    Good enough for the `absent` path where retrieval is best-effort.
+    The `present` path returns a real score from agent-memory.
+    """
+    if not keys:
+        return 0.1  # any hit beats no hit when there is no key
+    hay_parts: list[str] = []
+    for field_name in ("path", "key", "symptom", "feature", "rule", "body"):
+        v = entry.get(field_name)
+        if isinstance(v, str):
+            hay_parts.append(v)
+        elif isinstance(v, list):
+            hay_parts.extend(str(x) for x in v)
+    hay = " | ".join(hay_parts).lower()
+    best = 0.0
+    for k in keys:
+        kl = k.lower()
+        if fnmatch.fnmatch(hay, f"*{kl}*"):
+            best = max(best, 0.8)
+        elif kl in hay:
+            best = max(best, 0.6)
+    return best
+
+
+def retrieve(types: list[str], keys: list[str], limit: int = 5) -> list[Hit]:
+    """Return up to `limit` hits across the requested types, highest score first.
+
+    Curated entries are preferred on ties — they are hand-reviewed.
+    The shape (`Hit`) matches the `present` backend adapter so skills
+    can treat both sources identically.
+    """
+    hits: list[Hit] = []
+    for mtype in types:
+        if mtype not in CURATED_TYPES:
+            continue
+        for path, entry in _iter_curated_entries(mtype):
+            hits.append(Hit(
+                id=str(entry.get("id", "")),
+                type=mtype,
+                source="curated",
+                path=str(path),
+                score=_score(entry, keys),
+                entry=entry,
+            ))
+        for path, entry in _iter_intake_entries(mtype):
+            hits.append(Hit(
+                id=str(entry.get("id", "")),
+                type=mtype,
+                source="intake",
+                path=str(path),
+                score=_score(entry, keys) * 0.9,  # slight discount vs curated
+                entry=entry,
+            ))
+    hits.sort(key=lambda h: (h.score, h.source == "curated"), reverse=True)
+    # Drop zero-score hits unless no better option exists.
+    positives = [h for h in hits if h.score > 0]
+    return (positives or hits)[:limit]
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--types", default="",
+                    help="Comma-separated memory types (e.g., ownership,domain-invariants)")
+    ap.add_argument("--key", action="append", default=[],
+                    help="Retrieval key (repeatable)")
+    ap.add_argument("--limit", type=int, default=5)
+    ap.add_argument("--format", choices=["text", "json"], default="text")
+    args = ap.parse_args()
+    types = [t.strip() for t in args.types.split(",") if t.strip()]
+    if not types:
+        print("error: --types is required", file=sys.stderr)
+        return 2
+    hits = retrieve(types, args.key, args.limit)
+    if args.format == "json":
+        print(json.dumps([h.as_dict() for h in hits], indent=2, default=str))
+    else:
+        if not hits:
+            print("  (no hits)")
+        for h in hits:
+            print(f"  [{h.source}] {h.type}  score={h.score:.2f}  "
+                  f"id={h.id or '-'}  path={h.path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+"""One-shot memory observability report.
+
+Shows:
+  - Backend status (via `memory_status.status()`)
+  - Intake counts per entry type and per month
+  - Curated file staleness (files with `last_validated` older than
+    `review_after_days` for any entry)
+  - Supersede-chain totals
+
+Exit code: 0 = report printed (green or otherwise); 2 = PyYAML missing.
+`task memory:status` is the expected entry point, but the script is
+usable standalone.
+
+Usage:
+    python3 scripts/memory_report.py
+    python3 scripts/memory_report.py --format json
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import memory_status  # noqa: E402
+
+MEMORY_ROOT = Path("agents/memory")
+INTAKE_ROOT = MEMORY_ROOT / "intake"
+CURATED_TYPES = (
+    "ownership", "historical-patterns", "domain-invariants",
+    "architecture-decisions", "incident-learnings", "product-rules",
+)
+
+
+def _load_yaml(path: Path) -> dict:
+    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) or {}
+
+
+def _iter_curated_entries() -> list[tuple[Path, str, dict]]:
+    """Yield (file, type, entry) across both curated layouts."""
+    out: list[tuple[Path, str, dict]] = []
+    for mtype in CURATED_TYPES:
+        single = MEMORY_ROOT / f"{mtype}.yml"
+        if single.is_file():
+            data = _load_yaml(single)
+            for e in data.get("entries") or []:
+                if isinstance(e, dict):
+                    out.append((single, mtype, e))
+        type_dir = MEMORY_ROOT / mtype
+        if type_dir.is_dir():
+            for yml in sorted(type_dir.rglob("*.yml")):
+                data = _load_yaml(yml) or {}
+                entries = data.get("entries")
+                if isinstance(entries, list):
+                    for e in entries:
+                        if isinstance(e, dict):
+                            out.append((yml, mtype, e))
+                elif isinstance(data, dict) and data.get("id"):
+                    out.append((yml, mtype, data))
+    return out
+
+
+def _intake_stats() -> dict:
+    total = 0
+    by_type: Counter = Counter()
+    by_month: Counter = Counter()
+    superseded = 0
+    if INTAKE_ROOT.is_dir():
+        for jsonl in sorted(INTAKE_ROOT.glob("*.jsonl")):
+            month = jsonl.stem.replace("signals-", "")
+            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":
+                        superseded += 1
+                        continue
+                    total += 1
+                    t = obj.get("entry_type")
+                    if isinstance(t, str):
+                        by_type[t] += 1
+                    by_month[month] += 1
+    return {
+        "total_active": total,
+        "superseded": superseded,
+        "by_type": dict(by_type),
+        "by_month": dict(by_month),
+    }
+
+
+def _staleness_report() -> list[dict]:
+    today = dt.date.today()
+    stale: list[dict] = []
+    for path, mtype, entry in _iter_curated_entries():
+        lv = entry.get("last_validated")
+        review_after = entry.get("review_after_days")
+        if not isinstance(lv, (str, dt.date)) \
+                or not isinstance(review_after, int):
+            continue
+        try:
+            last = lv if isinstance(lv, dt.date) \
+                else dt.date.fromisoformat(str(lv))
+        except ValueError:
+            continue
+        due = last + dt.timedelta(days=review_after)
+        if due < today:
+            stale.append({
+                "file": str(path),
+                "type": mtype,
+                "id": entry.get("id", "?"),
+                "overdue_days": (today - due).days,
+            })
+    stale.sort(key=lambda r: r["overdue_days"], reverse=True)
+    return stale
+
+
+def build_report() -> dict:
+    status = memory_status.status()
+    return {
+        "backend": {
+            "status": status.status,
+            "backend": status.backend,
+            "reason": status.reason,
+            "cli_path": status.cli_path,
+        },
+        "intake": _intake_stats(),
+        "staleness": _staleness_report(),
+    }
+
+
+def _print_text(report: dict) -> None:
+    b = report["backend"]
+    print(f"Backend:   {b['status']} (backend={b['backend']})")
+    if b["reason"]:
+        print(f"           reason: {b['reason']}")
+    intake = report["intake"]
+    print(f"Intake:    {intake['total_active']} active, "
+          f"{intake['superseded']} superseded")
+    for t, n in sorted(intake["by_type"].items()):
+        print(f"  - {t}: {n}")
+    stale = report["staleness"]
+    if not stale:
+        print("Staleness: no curated entries past review_after_days")
+    else:
+        print(f"Staleness: {len(stale)} entrie(s) overdue")
+        for row in stale[:5]:
+            print(f"  - {row['id']} ({row['type']})  "
+                  f"+{row['overdue_days']}d  {row['file']}")
+        if len(stale) > 5:
+            print(f"  (+{len(stale) - 5} more)")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--format", choices=["text", "json"], default="text")
+    args = ap.parse_args()
+    report = build_report()
+    if args.format == "json":
+        print(json.dumps(report, indent=2, default=str))
+    else:
+        _print_text(report)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""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`).
+
+Rate limiting:
+- Per-path, per-type, within a rolling window (default 7 days).
+- Silent skip on duplicate — the producer's caller should not error,
+  since over-emission is a correctness bug, not a failure mode.
+
+Usage:
+    python3 scripts/memory_signal.py \\
+        --type historical-patterns \\
+        --path "app/Http/Controllers/Billing/Checkout.php" \\
+        --body "Null deref when currency is missing — add guard."
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+import secrets
+import sys
+from pathlib import Path
+from typing import Any
+
+INTAKE_ROOT = Path("agents/memory/intake")
+VALID_TYPES = {
+    "historical-patterns",
+    "incident-learnings",
+    "ownership",
+    "domain-invariants",
+    "architecture-decisions",
+    "product-rules",
+}
+RATE_LIMIT_WINDOW_DAYS = 7
+
+
+def _now_iso() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="seconds")
+
+
+def _new_id() -> str:
+    # Short, URL-safe, stable enough for intake ids.
+    return f"sig-{secrets.token_hex(6)}"
+
+
+def _monthly_file() -> Path:
+    ym = dt.datetime.now(dt.timezone.utc).strftime("%Y-%m")
+    return INTAKE_ROOT / f"signals-{ym}.jsonl"
+
+
+def _recently_emitted(entry_type: str, path: str, body: str,
+                      window_days: int = RATE_LIMIT_WINDOW_DAYS) -> bool:
+    """True if an identical (type, path, body) was written within the window."""
+    if not INTAKE_ROOT.is_dir():
+        return False
+    cutoff = dt.datetime.now(dt.timezone.utc) - dt.timedelta(days=window_days)
+    for jsonl in sorted(INTAKE_ROOT.glob("signals-*.jsonl")):
+        try:
+            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("entry_type") != entry_type:
+                        continue
+                    if obj.get("path") != path:
+                        continue
+                    if obj.get("body") != body:
+                        continue
+                    ts = obj.get("ts")
+                    if not isinstance(ts, str):
+                        continue
+                    try:
+                        emitted = dt.datetime.fromisoformat(ts)
+                    except ValueError:
+                        continue
+                    if emitted >= cutoff:
+                        return True
+        except OSError:
+            continue
+    return False
+
+
+def emit(entry_type: str, path: str, body: str,
+         extra: dict[str, Any] | None = None,
+         origin: str = "agent",
+         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.
+    """
+    if entry_type not in VALID_TYPES:
+        raise ValueError(f"unknown memory type: {entry_type}")
+    if not path or not body:
+        raise ValueError("path and body are required")
+    if not force and _recently_emitted(entry_type, path, body):
+        return None
+    record: dict[str, Any] = {
+        "id": _new_id(),
+        "ts": _now_iso(),
+        "origin": origin,
+        "entry_type": entry_type,
+        "path": path,
+        "body": body,
+    }
+    if extra:
+        # Reserved keys stay intact; extras only fill unclaimed slots.
+        for k, v in extra.items():
+            record.setdefault(k, v)
+    INTAKE_ROOT.mkdir(parents=True, exist_ok=True)
+    target = _monthly_file()
+    with target.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+    return record
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--type", dest="entry_type", required=True,
+                    choices=sorted(VALID_TYPES))
+    ap.add_argument("--path", required=True,
+                    help="Affected file/module path (e.g., app/Http/Foo.php)")
+    ap.add_argument("--body", required=True, help="One- to few-sentence finding")
+    ap.add_argument("--origin", default="agent",
+                    help="Producer identifier, e.g., bug-fix, do-and-judge")
+    ap.add_argument("--extra", default="",
+                    help="Optional JSON blob of extra keys (symptom, owner, ...)")
+    ap.add_argument("--force", action="store_true",
+                    help="Bypass rate-limit dedupe")
+    args = ap.parse_args()
+    extra: dict[str, Any] = {}
+    if args.extra:
+        try:
+            extra = json.loads(args.extra)
+            if not isinstance(extra, dict):
+                raise ValueError
+        except ValueError:
+            print("error: --extra must be a JSON object", file=sys.stderr)
+            return 2
+    rec = emit(args.entry_type, args.path, args.body,
+               extra=extra, origin=args.origin, force=args.force)
+    if rec is None:
+        print(f"  ℹ️  skipped (already emitted within "
+              f"{RATE_LIMIT_WINDOW_DAYS}d): {args.entry_type} @ {args.path}")
+        return 0
+    print(f"  ✅  signal emitted: id={rec['id']} type={rec['entry_type']} "
+          f"path={rec['path']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())