@event4u/agent-config 2.26.0 → 3.1.0

package/scripts/update_prices.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Refresh `agents/.agent-prices.md` from the LiteLLM model-prices feed.
+"""Refresh `agents/runtime/.agent-prices.md` from the LiteLLM model-prices feed.
 
 Source: https://raw.githubusercontent.com/BerriAI/litellm/main/
         model_prices_and_context_window.json
@@ -9,7 +9,7 @@ Network failure or invalid response → fall back to
 always written. Stdlib only; no extra dependency.
 
 Usage:
-    python3 scripts/update_prices.py            # writes agents/.agent-prices.md
+    python3 scripts/update_prices.py            # writes agents/runtime/.agent-prices.md
     python3 scripts/update_prices.py --check    # exit 1 if file is stale
 """
 
@@ -81,7 +81,8 @@ def _to_rows_from_litellm(payload: dict[str, dict[str, object]]) -> list[tuple[s
 
 
 def refresh(path: Path = PRICES_FILE) -> str:
-    """Write a fresh `agents/.agent-prices.md`. Returns the source label used."""
+    """Write a fresh `agents/runtime/.agent-prices.md`. Returns the source label used."""
+    path.parent.mkdir(parents=True, exist_ok=True)
     payload = _fetch_litellm()
     if payload is not None:
         rows = _to_rows_from_litellm(payload)

package/scripts/validate_decision_engine.py

@@ -27,7 +27,15 @@ except ImportError:  # pragma: no cover — bootstrap guard
     sys.exit(3)
 
 REPO_ROOT = Path(__file__).resolve().parent.parent
-TEMPLATE_SCRIPTS = REPO_ROOT / ".agent-src.uncompressed" / "templates" / "scripts"
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib.agent_src import resolve_logical  # noqa: E402
+
+# Post-ADR-017 the templates/ tree lives under packages/core/; fall back
+# to the legacy root for pre-move checkouts.
+_template_scripts = resolve_logical("templates/scripts")
+TEMPLATE_SCRIPTS = _template_scripts or (
+    REPO_ROOT / ".agent-src.uncompressed" / "templates" / "scripts"
+)
 if str(TEMPLATE_SCRIPTS) not in sys.path:
     sys.path.insert(0, str(TEMPLATE_SCRIPTS))
 

package/scripts/validate_discovery_manifest.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Stale-manifest guard — re-builds the manifest in memory and diffs it
+against the committed ``dist/discovery/discovery-manifest.json``.
+
+CI runs this after a freshly-checked-out tree; non-zero diff = somebody
+forgot to regenerate the manifest after touching artefact frontmatter.
+
+The ``generated_at`` field is normalised on both sides (wall-clock).
+Everything else MUST match byte-for-byte.
+
+CLI:
+  python scripts/validate_discovery_manifest.py [--quiet]
+
+Exit codes:
+  0  manifest on disk matches a fresh re-build
+  1  drift detected (committed manifest is stale)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCANNER = ROOT / "scripts" / "build_discovery_manifest.py"
+COMMITTED = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+
+
+def _normalise(manifest: dict) -> str:
+    out = dict(manifest)
+    out["generated_at"] = "<normalised>"
+    return json.dumps(out, indent=2, sort_keys=True, ensure_ascii=False) + "\n"
+
+
+def _fresh_build() -> dict:
+    proc = subprocess.run(
+        [sys.executable, str(SCANNER)],
+        capture_output=True,
+        text=True,
+        check=False,
+        cwd=str(ROOT),
+    )
+    if proc.returncode != 0:
+        print(proc.stderr, file=sys.stderr)
+        raise SystemExit(f"scanner failed: exit {proc.returncode}")
+    return json.loads(proc.stdout)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not COMMITTED.exists():
+        print(
+            f"error: committed manifest not found at {COMMITTED.relative_to(ROOT)} "
+            "— run `task build-discovery` and commit the output.",
+            file=sys.stderr,
+        )
+        return 1
+
+    committed = json.loads(COMMITTED.read_text(encoding="utf-8"))
+    fresh = _fresh_build()
+    sa = _normalise(committed)
+    sb = _normalise(fresh)
+    if sa != sb:
+        print(
+            "DRIFT: committed discovery-manifest.json differs from a fresh re-build.",
+            file=sys.stderr,
+        )
+        print(
+            "  Run `task build-discovery` and commit dist/discovery/.",
+            file=sys.stderr,
+        )
+        # first divergence — single most useful line
+        for i, (la, lb) in enumerate(zip(sa.splitlines(), sb.splitlines()), 1):
+            if la != lb:
+                print(f"  first diff at line {i}:", file=sys.stderr)
+                print(f"    committed: {la}", file=sys.stderr)
+                print(f"    fresh:     {lb}", file=sys.stderr)
+                break
+        return 1
+    if not args.quiet:
+        print(
+            f"OK {COMMITTED.relative_to(ROOT)} matches fresh re-build "
+            f"({committed['stats']['total_artefacts']} artefacts)."
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_frontmatter.py

@@ -428,32 +428,51 @@ def _main() -> int:
     )
     parser.add_argument(
         "--root",
-        default=".agent-src.uncompressed",
-        help="Source root to scan (default: .agent-src.uncompressed).",
+        default=None,
+        help=(
+            "Source root to scan. Default: every artefact root discovered by "
+            "scripts/_lib/agent_src.artefact_roots() (legacy + packages/*)."
+        ),
     )
     args = parser.parse_args()
 
-    root = Path(args.root)
-    if not root.is_dir():
-        print(f"error: source root not found: {root}", file=sys.stderr)
-        return 2
+    if args.root is not None:
+        root = Path(args.root)
+        if not root.is_dir():
+            print(f"error: source root not found: {root}", file=sys.stderr)
+            return 2
+        roots = [root]
+    else:
+        # Late import keeps the validator usable as a library without the
+        # monorepo-helper dependency on the import path.
+        sys.path.insert(0, str(Path(__file__).resolve().parent))
+        from _lib.agent_src import artefact_roots  # noqa: E402
+        roots = artefact_roots()
+        if not roots:
+            print(
+                "error: no artefact roots found "
+                "(checked .agent-src.uncompressed/ and packages/*/.agent-src.uncompressed/)",
+                file=sys.stderr,
+            )
+            return 2
 
     total = 0
     failing = 0
-    for artefact_type, path in _iter_artefacts(root):
-        total += 1
-        text = path.read_text(encoding="utf-8")
-        data, _offset = parse_frontmatter(text)
-        if data is None:
-            # Other tooling flags missing frontmatter; don't double-report.
-            continue
-        schema = load_schema(artefact_type)
-        errors = validate(data, schema)
-        if errors:
-            failing += 1
-            for error in errors:
-                print(f"[{artefact_type}] {path}: {error.rule} at "
-                      f"{error.path} – {error.message}")
+    for root in roots:
+        for artefact_type, path in _iter_artefacts(root):
+            total += 1
+            text = path.read_text(encoding="utf-8")
+            data, _offset = parse_frontmatter(text)
+            if data is None:
+                # Other tooling flags missing frontmatter; don't double-report.
+                continue
+            schema = load_schema(artefact_type)
+            errors = validate(data, schema)
+            if errors:
+                failing += 1
+                for error in errors:
+                    print(f"[{artefact_type}] {path}: {error.rule} at "
+                          f"{error.path} – {error.message}")
 
     print(f"\n== Frontmatter schema: {total} artefacts, "
           f"{failing} failing ==")

package/scripts/verify_before_complete_hook.py

@@ -11,7 +11,7 @@ Wired to multiple events via the manifest:
   - post_tool_use → inspect tool + command, record verifications
   - stop                                → record stop fired (claim-done window)
 
-Output: `agents/state/verify-before-complete.json`
+Output: `agents/runtime/state/verify-before-complete.json`
   {
     "schema_version": 1,
     "session_id": "<str>",

package/scripts/verify_physical_move.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""Verify the post-move state matches the pre-move snapshot byte-for-byte.
+
+Re-runs `task sync` + `task build-discovery` (caller invokes them
+ahead of this script), then loads the fresh outputs and compares them
+against `dist/migration/pre-move-snapshot.json`. The contract:
+
+- `.agent-src/` tree hashes must match exactly
+- `.augment/` tree hashes must match exactly
+- `dist/discovery/discovery-manifest.json` with `artefacts[].path`
+  stripped + `generated_at` dropped must match exactly
+
+Anything else is a regression — exit non-zero with a diff summary.
+
+CLI:
+  --snapshot PATH   path to pre-move snapshot JSON
+  --json            machine-readable verdict to stdout
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from snapshot_agent_outputs import (  # noqa: E402
+    _build_snapshot,
+    _logical_path,
+    _SKIP_DIRS,
+    _SKIP_NAMES,
+)
+
+
+def _normalise_loaded_snapshot(snap: dict[str, Any]) -> None:
+    """Re-apply current snapshot filters to a previously-captured snapshot.
+
+    The pre-move snapshot file is immutable history; this lets verify
+    compare it against a freshly-captured post-move snapshot whose
+    filters have evolved (runtime-cache exclusion, logical-path stripping,
+    volatile-field drop) without regenerating the reference.
+    """
+    for key, tree in (snap.get("trees") or {}).items():
+        keep = {}
+        for path, sha in tree.items():
+            name = path.rsplit("/", 1)[-1]
+            if name in _SKIP_NAMES:
+                continue
+            if any(part in _SKIP_DIRS for part in path.split("/")):
+                continue
+            keep[path] = sha
+        snap["trees"][key] = keep
+    m = snap.get("manifest_path_stripped")
+    if isinstance(m, dict):
+        for k in ("unassigned", "documented_unassigned"):
+            entries = m.get(k) or []
+            normalised: list[dict[str, Any]] = []
+            for e in entries:
+                if not isinstance(e, dict):
+                    normalised.append(e)
+                    continue
+                if "path" in e:
+                    e["path"] = _logical_path(e["path"])
+                path = e.get("path", "")
+                name = path.rsplit("/", 1)[-1]
+                if name in _SKIP_NAMES:
+                    continue
+                if any(part in _SKIP_DIRS for part in path.split("/")):
+                    continue
+                normalised.append(e)
+            normalised.sort(key=lambda e: (e.get("path", ""), e.get("category", "")))
+            m[k] = normalised
+        # Recompute the two counts that ride on the filtered lists so the
+        # stats block stays consistent with the normalised entries.
+        stats = m.get("stats")
+        if isinstance(stats, dict):
+            stats["documented_unassigned_count"] = len(m.get("documented_unassigned") or [])
+            stats["unassigned_count"] = len(m.get("unassigned") or [])
+        # Re-sort artefacts by (category, checksum) — pre-move snapshot
+        # was sorted by path; that order shifts when files move roots.
+        arts = m.get("artefacts") or []
+        for a in arts:
+            a.pop("path", None)
+        arts.sort(key=lambda a: (a.get("category", ""), a.get("checksum", "")))
+        m["artefacts"] = arts
+        m.pop("checksum", None)
+        m.pop("scanner_version", None)
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_SNAPSHOT = ROOT / "dist" / "migration" / "pre-move-snapshot.json"
+
+
+def _diff_tree(name: str, before: dict[str, str], after: dict[str, str]) -> list[str]:
+    issues: list[str] = []
+    keys = sorted(set(before) | set(after))
+    for k in keys:
+        b = before.get(k)
+        a = after.get(k)
+        if b is None:
+            issues.append(f"  {name}: added   {k}")
+        elif a is None:
+            issues.append(f"  {name}: removed {k}")
+        elif a != b:
+            issues.append(f"  {name}: changed {k}  ({b[:12]}… → {a[:12]}…)")
+    return issues
+
+
+def _diff_manifest(before: dict[str, Any] | None, after: dict[str, Any] | None) -> list[str]:
+    if before is None and after is None:
+        return []
+    if before is None:
+        return ["  manifest: pre-move snapshot missing"]
+    if after is None:
+        return ["  manifest: post-move manifest missing"]
+    before_str = json.dumps(before, sort_keys=True, ensure_ascii=False)
+    after_str = json.dumps(after, sort_keys=True, ensure_ascii=False)
+    if before_str == after_str:
+        return []
+    # Field-level diff for visibility.
+    issues = ["  manifest: path-stripped content differs"]
+    b_arts = {a.get("name", "?"): a for a in (before.get("artefacts") or [])}
+    a_arts = {a.get("name", "?"): a for a in (after.get("artefacts") or [])}
+    only_b = sorted(set(b_arts) - set(a_arts))
+    only_a = sorted(set(a_arts) - set(b_arts))
+    for n in only_b[:10]:
+        issues.append(f"    artefact removed: {n}")
+    for n in only_a[:10]:
+        issues.append(f"    artefact added:   {n}")
+    common_changed = []
+    for n in sorted(set(b_arts) & set(a_arts)):
+        if json.dumps(b_arts[n], sort_keys=True) != json.dumps(a_arts[n], sort_keys=True):
+            common_changed.append(n)
+    for n in common_changed[:10]:
+        issues.append(f"    artefact changed: {n}")
+    return issues
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--snapshot", type=Path, default=DEFAULT_SNAPSHOT)
+    ap.add_argument("--json", action="store_true", help="emit machine-readable verdict to stdout")
+    args = ap.parse_args()
+
+    if not args.snapshot.exists():
+        print(f"ERROR: snapshot missing: {args.snapshot}", file=sys.stderr)
+        return 2
+
+    before = json.loads(args.snapshot.read_text(encoding="utf-8"))
+    after = _build_snapshot()
+
+    # The pre-move snapshot was captured before _hash_tree / manifest
+    # stripping learned to filter runtime artefacts. Re-apply the current
+    # filter to the loaded snapshot so the diff is apples-to-apples.
+    _normalise_loaded_snapshot(before)
+
+    issues: list[str] = []
+    for key in (".agent-src", ".augment"):
+        issues.extend(_diff_tree(key, before["trees"].get(key, {}), after["trees"].get(key, {})))
+    issues.extend(_diff_manifest(before.get("manifest_path_stripped"), after.get("manifest_path_stripped")))
+
+    ok = not issues
+    if args.json:
+        print(json.dumps({
+            "ok": ok,
+            "issue_count": len(issues),
+            "issues": issues,
+        }, indent=2))
+    else:
+        if ok:
+            print("verify_physical_move: byte-identity OK")
+            print(f"  .agent-src/ files: {len(after['trees'].get('.agent-src', {}))}")
+            print(f"  .augment/   files: {len(after['trees'].get('.augment', {}))}")
+            print(f"  manifest: path-stripped content matches")
+        else:
+            print(f"verify_physical_move: FAIL ({len(issues)} issue(s))")
+            for line in issues[:50]:
+                print(line)
+            if len(issues) > 50:
+                print(f"  … and {len(issues) - 50} more")
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/verify_roadmap_closure.py

@@ -219,7 +219,7 @@ def verify_concept(name: str) -> bool:
     try:
         r = subprocess.run(
             ["git", "grep", "-l", "-w", name, "--",
-             ".agent-src.uncompressed/", "docs/", "scripts/", "agents/contexts/"],
+             ".agent-src.uncompressed/", "docs/", "scripts/", "agents/settings/contexts/"],
             cwd=REPO, capture_output=True, text=True, timeout=15,
         )
         return bool(r.stdout.strip())

package/templates/agent-user.md

@@ -0,0 +1,34 @@
+---
+version: 1
+identity:
+    name: ""
+language: "en"
+role:
+    - ""
+style:
+    formality: "informal"
+    pace: "pragmatic"
+voice_sample: |
+    Replace this block with one to three sentences in your own
+    writing style. The agent uses it as a tone anchor — paste the
+    way you would actually message a colleague, not a polished pitch.
+last_updated: "1970-01-01"
+---
+
+# Notes
+
+This file captures who you are and how you want the agent to address
+you. It is created by `/agents user init` (chat) or the setup wizard
+(`agent-config settings`). The file is gitignored by default — your
+voice never lands in the repository unless you opt in with
+`--shared`.
+
+Hard cap: 100 lines total, frontmatter + body, enforced by
+`/agents user accept` and `/agents user update`.
+
+Replace this paragraph with anything you want the agent to remember
+about you across sessions — preferred terminology, recurring
+projects, conventions you want enforced. Keep it short; everything
+here loads into every reply.
+
+> Schema reference: [`docs/contracts/agent-user-schema.md`](docs/contracts/agent-user-schema.md).

package/templates/agent-user.yml

@@ -0,0 +1,21 @@
+version: 1
+identity:
+    name: ""
+language: "en"
+role:
+    - ""
+style:
+    formality: "informal"
+    pace: "pragmatic"
+voice_sample: |
+    Replace this block with one to three sentences in your own
+    writing style. The agent uses it as a tone anchor — paste the
+    way you would actually message a colleague, not a polished pitch.
+last_updated: "1970-01-01"
+# notes: |
+#     Optional free-form prose. Anything you want the agent to remember
+#     across sessions — preferred terminology, recurring projects,
+#     conventions you want enforced. Keep it short; everything here
+#     loads into every reply. Hard cap: 8 000 chars.
+#
+# Schema reference: docs/contracts/agent-user-schema.md

package/templates/minimal/agents-overrides-readme.md

@@ -0,0 +1,46 @@
+# Project overrides
+
+Project-local override layer for `@event4u/agent-config` (see ADR-020 — consumer
+installs are global-only). Files dropped under the directories below replace or
+extend their global counterparts from `~/.event4u/agent-config/`.
+
+## Layout
+
+```
+agents/overrides/
+├── rules/      # Always-active behaviour rules (project-scoped)
+├── skills/     # On-demand domain skills (project-scoped)
+└── commands/   # Slash commands (project-scoped)
+```
+
+The `.gitkeep` placeholder in each subdir is committable so a fresh consumer
+repo can track the structure before any actual overrides are added.
+
+## How overrides resolve
+
+Highest precedence wins:
+
+1. `agents/overrides/<kind>/<name>.md` — this project (wins on name match)
+2. `~/.event4u/agent-config/<kind>/<name>.md` — user-global shared layer
+3. Bundled defaults that ship with the package
+
+Drop a file under `agents/overrides/rules/foo.md` to override the global
+`foo.md` rule for this project only; delete the file to revert to the global
+copy. The bridge anchor at `agents/.event4u-bridge.yml` tells the loader which
+`~/.event4u/agent-config/` install to pair with.
+
+## Adding your first override
+
+```bash
+# Start from the global copy so you only edit the deltas:
+cp ~/.event4u/agent-config/rules/<name>.md agents/overrides/rules/<name>.md
+$EDITOR agents/overrides/rules/<name>.md
+```
+
+Run `agent-config doctor` afterwards to confirm the loader sees the override.
+
+## Settings
+
+Project-local `.agent-settings.yml` is **tolerated but not required**. Effective
+settings merge `defaults < global < project-overrides`; see
+`docs/contracts/layered-settings.md` (in the package) for the precedence model.

package/templates/minimal/overrides-gitkeep

@@ -0,0 +1,2 @@
+# Placeholder so this overrides subdir is committable in a fresh consumer repo.
+# Drop project-scoped overrides next to this file (see agents/overrides/README.md).