@event4u/agent-config 3.0.0 → 3.1.0

package/scripts/smoke_quickstart.py

@@ -20,6 +20,7 @@ Exit codes: 0 = green; 1 = one or more checks failed; 2 = setup error.
 """
 from __future__ import annotations
 
+import os
 import shutil
 import subprocess
 import sys
@@ -49,8 +50,10 @@ def _check_installer_runs(tmpdir: Path) -> tuple[int, Path | None]:
         str(ROOT),
         "--skip-bridges",
     ]
+    # ADR-020: --project is reserved for maintainers; CI is a maintainer context.
+    env = {**os.environ, "AGENT_CONFIG_DEV_MODE": "1"}
     try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60)
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60, env=env)
     except subprocess.TimeoutExpired:
         return _fail("installer timed out after 60s"), None
     if result.returncode != 0:
@@ -82,7 +85,13 @@ def _check_default_profile(settings: Path) -> int:
 
 def _check_decision_engine_block(settings: Path) -> int:
     """Step 3 — decision_engine block parses through the engine parser."""
-    sys.path.insert(0, str(ROOT / ".agent-src.uncompressed" / "templates" / "scripts"))
+    sys.path.insert(0, str(ROOT / "scripts"))
+    from _lib.agent_src import resolve_logical  # noqa: E402
+
+    template_scripts = resolve_logical("templates/scripts") or (
+        ROOT / ".agent-src.uncompressed" / "templates" / "scripts"
+    )
+    sys.path.insert(0, str(template_scripts))
     try:
         from work_engine.scoring.decision_engine import (  # type: ignore[import-not-found]
             DecisionEngineSettings,

package/scripts/snapshot_agent_outputs.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Snapshot the agent-config build outputs for byte-identity verification.
+
+Used by monorepo Phase 4 (physical layout move) to assert that the
+pre-move and post-move `task sync` + `task build-discovery` outputs
+match byte-for-byte except for `artefacts[].path` values.
+
+Captures sha256 of every file under:
+  - .agent-src/
+  - .augment/
+  - dist/discovery/discovery-manifest.json (also stores parsed copy
+    with paths stripped so the post-move diff is path-only)
+
+CLI:
+  --out PATH    write JSON to this path (default: dist/migration/pre-move-snapshot.json)
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_OUT = ROOT / "dist" / "migration" / "pre-move-snapshot.json"
+
+TARGETS = (
+    ROOT / ".agent-src",
+    ROOT / ".augment",
+)
+MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
+
+
+def _sha256(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+# Runtime artefacts that never participate in byte-identity verification.
+# Eval last-run.json + pytest caches are gitignored; including them just
+# adds noise when the worktree is clean.
+_SKIP_NAMES = frozenset({"last-run.json"})
+_SKIP_DIRS = frozenset({".pytest_cache", "__pycache__", ".mypy_cache",
+                         ".ruff_cache", "node_modules", ".DS_Store"})
+
+
+def _hash_tree(root: Path) -> dict[str, str]:
+    if not root.exists():
+        return {}
+    hashes: dict[str, str] = {}
+    for p in sorted(root.rglob("*")):
+        if not p.is_file():
+            continue
+        if p.name in _SKIP_NAMES:
+            continue
+        if any(part in _SKIP_DIRS for part in p.parts):
+            continue
+        hashes[p.relative_to(ROOT).as_posix()] = _sha256(p)
+    return hashes
+
+
+def _logical_path(rel: str) -> str:
+    """Strip any source-root prefix (legacy or packages/*) so the diff
+    compares the artefact's logical identity, not its physical location.
+    Non-source paths are returned unchanged.
+    """
+    posix = rel.replace("\\", "/")
+    if posix.startswith(".agent-src.uncompressed/"):
+        return posix[len(".agent-src.uncompressed/"):]
+    if posix.startswith("packages/"):
+        marker = "/.agent-src.uncompressed/"
+        idx = posix.find(marker)
+        if idx != -1:
+            return posix[idx + len(marker):]
+    return posix
+
+
+def _manifest_path_stripped(manifest_path: Path) -> dict[str, Any] | None:
+    if not manifest_path.exists():
+        return None
+    data = json.loads(manifest_path.read_text(encoding="utf-8"))
+    # Strip `path` from every artefact so the diff is path-only, then
+    # re-sort by (category, checksum) so the list order is content-stable
+    # — the original sort is path-based, which shifts when files move
+    # between roots even though no artefact body changed.
+    artefacts = data.get("artefacts", []) or []
+    for a in artefacts:
+        a.pop("path", None)
+    artefacts.sort(key=lambda a: (a.get("category", ""), a.get("checksum", "")))
+    data["artefacts"] = artefacts
+    # Normalise unassigned / documented_unassigned to logical paths and
+    # re-sort so the post-move diff is content-only.
+    for key in ("unassigned", "documented_unassigned"):
+        entries = data.get(key) or []
+        for e in entries:
+            if isinstance(e, dict) and "path" in e:
+                e["path"] = _logical_path(e["path"])
+        entries.sort(key=lambda e: (e.get("path", ""), e.get("category", "")))
+        data[key] = entries
+    # Drop volatile fields: timestamp, the manifest's own checksum (which
+    # covers everything above and changes with any path text), and the
+    # scanner_version (sha of the build script — moves with code edits).
+    data.pop("generated_at", None)
+    data.pop("checksum", None)
+    data.pop("scanner_version", None)
+    return data
+
+
+def _build_snapshot() -> dict[str, Any]:
+    snap: dict[str, Any] = {"schema_version": "1", "trees": {}}
+    for tgt in TARGETS:
+        key = tgt.relative_to(ROOT).as_posix()
+        snap["trees"][key] = _hash_tree(tgt)
+    snap["manifest_sha256"] = _sha256(MANIFEST) if MANIFEST.exists() else None
+    snap["manifest_path_stripped"] = _manifest_path_stripped(MANIFEST)
+    return snap
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--out", type=Path, default=DEFAULT_OUT)
+    args = ap.parse_args()
+
+    snap = _build_snapshot()
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(
+        json.dumps(snap, indent=2, sort_keys=True, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    n_files = sum(len(t) for t in snap["trees"].values())
+    print(f"Snapshot: {args.out.relative_to(ROOT)}")
+    print(f"  files hashed     : {n_files}")
+    print(f"  trees            : {list(snap['trees'])}")
+    print(f"  manifest sha256  : {snap['manifest_sha256'][:16] if snap['manifest_sha256'] else 'MISSING'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/update_counts.py

@@ -20,31 +20,59 @@ import re
 import sys
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _lib.agent_src import artefact_roots  # noqa: E402
+
 REPO_ROOT = Path(__file__).resolve().parent.parent
-SRC = REPO_ROOT / ".agent-src.uncompressed"
 
 
 def count(kind: str) -> int:
-    if kind == "skills":
-        return sum(1 for _ in (SRC / "skills").rglob("SKILL.md"))
     if kind == "guidelines":
         # Guidelines live under docs/guidelines/{topic}/ — they are reference
         # material, not packaged artefacts. Recursive walk to count every .md.
         return sum(1 for _ in (REPO_ROOT / "docs" / "guidelines").rglob("*.md"))
-    if kind == "personas":
-        # personas live as flat .md files, README excluded
-        pdir = SRC / "personas"
-        if not pdir.exists():
-            return 0
-        return sum(1 for f in pdir.glob("*.md") if f.name != "README.md")
-    if kind == "commands":
-        # Commands may be flat (`commands/<name>.md`) or nested under a
-        # cluster directory (`commands/<cluster>/<sub>.md`). Walk the tree
-        # and skip the AGENTS.md reference orchestrator.
-        return sum(
-            1 for f in (SRC / kind).rglob("*.md") if f.name != "AGENTS.md"
-        )
-    return sum(1 for _ in (SRC / kind).glob("*.md"))
+    total = 0
+    seen: set[str] = set()
+    for root in artefact_roots():
+        subdir = root / kind
+        if not subdir.exists():
+            continue
+        if kind == "skills":
+            for f in subdir.rglob("SKILL.md"):
+                rel = f.relative_to(root).as_posix()
+                if rel in seen:
+                    continue
+                seen.add(rel)
+                total += 1
+        elif kind == "personas":
+            # personas live as flat .md files, README excluded
+            for f in subdir.glob("*.md"):
+                if f.name == "README.md":
+                    continue
+                rel = f.relative_to(root).as_posix()
+                if rel in seen:
+                    continue
+                seen.add(rel)
+                total += 1
+        elif kind == "commands":
+            # Commands may be flat or nested under a cluster directory.
+            # Skip the AGENTS.md reference orchestrator.
+            for f in subdir.rglob("*.md"):
+                if f.name == "AGENTS.md":
+                    continue
+                rel = f.relative_to(root).as_posix()
+                if rel in seen:
+                    continue
+                seen.add(rel)
+                total += 1
+        else:
+            for f in subdir.glob("*.md"):
+                rel = f.relative_to(root).as_posix()
+                if rel in seen:
+                    continue
+                seen.add(rel)
+                total += 1
+    return total
 
 
 # file → list of (regex, kind)

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_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/templates/agent-user.md

@@ -2,7 +2,6 @@
 version: 1
 identity:
     name: ""
-    nickname: ""
 language: "en"
 role:
     - ""

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