@event4u/agent-config 2.25.0 → 3.0.0

package/scripts/sync_github_metadata.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Sync `.github/topics.yml` + `.github/about.yml` to the GitHub repo.
+
+Reads two on-disk manifests and pushes them via the REST API:
+  * `PUT  /repos/{owner}/{repo}/topics`   \u2014 topics list
+  * `PATCH /repos/{owner}/{repo}`         \u2014 description + homepage
+
+Default mode is `--dry-run`: fetches remote state, prints a unified
+diff (remote \u2192 desired), exits 0 (or 2 if drift exists when
+`--strict` is passed). `--apply` is required to mutate; it also
+appends an audit row to `agents/evidence/notes/visibility-sync-audit.md`.
+
+Auth: `GITHUB_TOKEN` env var. The repo slug is taken from
+`package.json` `repository.url` (parsed) or `--repo owner/name`.
+
+Stdlib only \u2014 `urllib.request` matches the convention in
+`scripts/_lib/update_check.py`.
+
+Roadmap: agents/roadmaps/strategic-visibility-mcp-topics-positioning.md Phase 1.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import difflib
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+TOPICS_FILE = ROOT / ".github" / "topics.yml"
+ABOUT_FILE = ROOT / ".github" / "about.yml"
+AUDIT_FILE = ROOT / "agents" / "notes" / "visibility-sync-audit.md"
+API = "https://api.github.com"
+
+
+def _load_yaml(path: Path) -> dict:
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def _resolve_repo(explicit: str | None) -> str:
+    if explicit:
+        return explicit
+    pkg = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+    url = (pkg.get("repository") or {}).get("url") or ""
+    m = re.search(r"github\.com[:/]+([^/]+/[^/.]+)", url)
+    if not m:
+        sys.exit("ERROR: cannot resolve owner/repo from package.json; pass --repo")
+    return m.group(1)
+
+
+def _request(method: str, url: str, token: str, body: dict | None = None) -> dict:
+    data = json.dumps(body).encode("utf-8") if body is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    req.add_header("Authorization", f"Bearer {token}")
+    req.add_header("Accept", "application/vnd.github+json")
+    req.add_header("X-GitHub-Api-Version", "2022-11-28")
+    req.add_header("User-Agent", "event4u-agent-config-sync")
+    if body is not None:
+        req.add_header("Content-Type", "application/json")
+    try:
+        with urllib.request.urlopen(req, timeout=20) as resp:  # noqa: S310
+            return json.loads(resp.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        sys.exit(f"ERROR: {method} {url} \u2192 HTTP {e.code}: {e.read().decode('utf-8', 'replace')[:300]}")
+    except urllib.error.URLError as e:
+        sys.exit(f"ERROR: {method} {url} \u2192 {e.reason}")
+
+
+def _diff(label: str, remote, desired) -> list[str]:
+    a = json.dumps(remote, indent=2, sort_keys=True).splitlines()
+    b = json.dumps(desired, indent=2, sort_keys=True).splitlines()
+    return list(difflib.unified_diff(a, b, fromfile=f"remote/{label}", tofile=f"desired/{label}", lineterm=""))
+
+
+def _audit(repo: str, mutations: list[str]) -> None:
+    AUDIT_FILE.parent.mkdir(parents=True, exist_ok=True)
+    if not AUDIT_FILE.exists():
+        AUDIT_FILE.write_text("# Visibility sync audit log\n\nAppend-only. Every `--apply` run logs one block.\n", encoding="utf-8")
+    ts = _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    block = [f"\n## {ts} \u2014 {repo}\n"]
+    block.extend(f"- {m}\n" for m in mutations)
+    with AUDIT_FILE.open("a", encoding="utf-8") as f:
+        f.writelines(block)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--apply", action="store_true", help="actually mutate the remote (default: dry-run)")
+    ap.add_argument("--strict", action="store_true", help="exit 2 if drift exists (dry-run only)")
+    ap.add_argument("--quiet", action="store_true")
+    ap.add_argument("--repo", help="owner/name (default: parsed from package.json)")
+    args = ap.parse_args()
+
+    repo = _resolve_repo(args.repo)
+    token = os.environ.get("GITHUB_TOKEN")
+    if not token:
+        sys.exit("ERROR: GITHUB_TOKEN not set")
+
+    topics_doc = _load_yaml(TOPICS_FILE)
+    about_doc = _load_yaml(ABOUT_FILE)
+    desired_topics = sorted(topics_doc.get("topics") or [])
+    desired_about = {"description": about_doc.get("description", ""), "homepage": about_doc.get("homepage", "")}
+
+    remote_topics = sorted((_request("GET", f"{API}/repos/{repo}/topics", token).get("names") or []))
+    repo_payload = _request("GET", f"{API}/repos/{repo}", token)
+    remote_about = {"description": repo_payload.get("description") or "", "homepage": repo_payload.get("homepage") or ""}
+
+    topic_diff = _diff("topics", remote_topics, desired_topics)
+    about_diff = _diff("about", remote_about, desired_about)
+    has_drift = bool(topic_diff or about_diff)
+
+    if not args.quiet:
+        if topic_diff:
+            print("\n".join(topic_diff))
+        if about_diff:
+            print("\n".join(about_diff))
+        if not has_drift:
+            print(f"\u2705  {repo}: topics + about already in sync")
+
+    if not args.apply:
+        return 2 if (has_drift and args.strict) else 0
+
+    mutations: list[str] = []
+    if topic_diff:
+        _request("PUT", f"{API}/repos/{repo}/topics", token, {"names": desired_topics})
+        mutations.append(f"topics \u2192 {desired_topics}")
+    if about_diff:
+        _request("PATCH", f"{API}/repos/{repo}", token, desired_about)
+        mutations.append(f"about \u2192 {desired_about}")
+    if mutations:
+        _audit(repo, mutations)
+        if not args.quiet:
+            print(f"\u2705  {repo}: applied {len(mutations)} mutation(s); audit appended")
+    elif not args.quiet:
+        print(f"\u2705  {repo}: nothing to apply")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/sync_gitignore.py

@@ -41,17 +41,27 @@ DEFAULT_GITIGNORE = ".gitignore"
 DEFAULT_TEMPLATE = Path(__file__).resolve().parent.parent / "config" / "gitignore-block.txt"
 
 # Legacy patterns that lived in older versions of config/gitignore-block.txt
-# before runtime artefacts moved under /agents/ (May 2026). They get stripped
-# wherever they appear in the consumer's .gitignore — inside the managed block
-# or outside (older installers / hand-edits). Current canonical equivalents
-# (e.g. /agents/.agent-chat-history) come from the template and are NOT
-# affected. Leading-slash variants are matched defensively.
+# before runtime artefacts moved under /agents/runtime/ (May 2026). They get
+# stripped wherever they appear in the consumer's .gitignore — inside the
+# managed block or outside (older installers / hand-edits). Current canonical
+# equivalents (e.g. /agents/runtime/.agent-prices.md) come from the template
+# and are NOT affected. Leading-slash variants are matched defensively.
 LEGACY_PATTERNS: tuple[str, ...] = (
     ".agent-chat-history",
     ".agent-chat-history.bak",
     ".agent-chat-history.*.bak",
     ".agent-prices.md",
     ".council-tmp/",
+    # 2.x intermediate: prices cache lived directly under agents/ before
+    # consolidating under agents/runtime/.
+    "agents/.agent-prices.md",
+    # Budget history JSONLs — previously listed explicitly at project
+    # root or under agents/; now covered by the /agents/runtime/
+    # catch-all in the managed block.
+    ".augment-budget-history.jsonl",
+    ".rule-budget-history.jsonl",
+    "agents/.augment-budget-history.jsonl",
+    "agents/.rule-budget-history.jsonl",
 )
 
 

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/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_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,35 @@
+---
+version: 1
+identity:
+    name: ""
+    nickname: ""
+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).