feat: add Timmy Gemma4 Mac wiring helper (#543)

docs/UNIFIED_FLEET_SOVEREIGNTY_STATUS.md

@@ -1,107 +0,0 @@
-# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration
-
-Grounding report for `timmy-home #524`.
-
-Issue #524 is a multi-lane directive, not a one-commit feature. This report grounds the directive in repo evidence, highlights stale cross-links, and names the missing operator bundles that still need real execution.
-
-This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.
-
-## Directive Snapshot
-
-- Repo-grounded workstreams: 0
-- Partial workstreams: 4
-- Missing workstreams: 1
-- Drifted references: 4
-
-## Reference Drift
-
-- #813 is cited for Nostr Migration Leadership, but its current title is 'docs: refresh the-playground genome analysis (#671)'.
-- #819 is cited for Nostr Migration Leadership, but its current title is 'docs: verify #648 already implemented (closes #818)'.
-- #139 is cited for v0.7.0 Feature Audit, but its current title is '🐣 Allegro-Primus is born'.
-- #103 is cited for Morrowind Local-First Benchmark, but its current title is 'Build comprehensive caching layer — cache everywhere'.
-
-## Workstream Matrix
-
-### 1. Nostr Migration Leadership — PARTIAL
-
-- Requirement: Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.
-- Referenced issues:
-  - #813 (closed) — docs: refresh the-playground genome analysis (#671) [DRIFT]
-  - #819 (open) — docs: verify #648 already implemented (closes #818) [DRIFT]
-- Repo evidence present:
-  - `infrastructure/timmy-bridge/client/timmy_client.py` — Nostr event client scaffold already exists
-  - `infrastructure/timmy-bridge/monitor/timmy_monitor.py` — Nostr relay monitor already exists
-  - `specs/wizard-telegram-bot-cutover.md` — Telegram cutover planning exists, so the migration lane is real
-- Missing operator deliverables:
-  - wizard keypair inventory and ownership matrix
-  - NIP-29 relay group verification report
-  - operator runbook for cutting traffic off Telegram
-- Why this lane remains open: The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.
-
-### 2. Lexicon Enforcement — PARTIAL
-
-- Requirement: Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.
-- Referenced issues:
-  - #388 (closed) — [KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents [aligned]
-- Repo evidence present:
-  - `docs/WIZARD_APPRENTICESHIP_CHARTER.md` — The repo already uses wizard-language canon in docs
-  - `specs/timmy-ezra-bezalel-canon-sheet.md` — Canonical agent naming already exists
-  - `docs/OPERATIONS_DASHBOARD.md` — Operational roles are already described in repo language
-- Missing operator deliverables:
-  - machine-checkable lexicon policy for review/triage
-  - terminology lint or reviewer checklist tied to the lexicon
-- Why this lane remains open: The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.
-
-### 3. v0.7.0 Feature Audit — PARTIAL
-
-- Requirement: Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.
-- Referenced issues:
-  - #139 (open) — 🐣 Allegro-Primus is born [DRIFT]
-- Repo evidence present:
-  - `scripts/sovereignty_audit.py` — Cloud-vs-local audit machinery already exists
-  - `reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md` — Recent sovereignty audit report is committed
-  - `timmy-local/README.md` — Local-first status is already documented for operators
-- Missing operator deliverables:
-  - Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
-  - Sovereignty Implementation Plan derived from that feature audit
-- Why this lane remains open: The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.
-
-### 4. Morrowind Local-First Benchmark — PARTIAL
-
-- Requirement: Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.
-- Referenced issues:
-  - #103 (open) — Build comprehensive caching layer — cache everywhere [DRIFT]
-- Repo evidence present:
-  - `morrowind/local_brain.py` — Local Morrowind control loop already exists
-  - `morrowind/mcp_server.py` — Morrowind MCP control surface is already wired
-  - `morrowind/pilot.py` — Trajectory logging for evaluation already exists
-- Missing operator deliverables:
-  - cloud-vs-local benchmark report for the combat loop
-  - reasoning-gap writeup tied to a proposed LoRA/fine-tune path
-- Why this lane remains open: The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.
-
-### 5. Infrastructure Hardening / Syntax Guard — MISSING
-
-- Requirement: Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.
-- Referenced issues: none listed in the directive body
-- Repo evidence present: none
-- Missing operator deliverables:
-  - repo inventory of Gitea targets that should carry Syntax Guard
-  - deployment verifier for hook presence across those repos
-  - operator report proving installation state instead of assuming it
-- Why this lane remains open: No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.
-
-## Highest-Leverage Next Actions
-
-- Nostr Migration Leadership: wizard keypair inventory and ownership matrix
-- Lexicon Enforcement: machine-checkable lexicon policy for review/triage
-- v0.7.0 Feature Audit: Hermes v0.7.0 feature inventory linked to cloud-reduction leverage
-- Morrowind Local-First Benchmark: cloud-vs-local benchmark report for the combat loop
-- Infrastructure Hardening / Syntax Guard: repo inventory of Gitea targets that should carry Syntax Guard
-
-## Why #524 Remains Open
-
-- The directive bundles five separate workstreams with different evidence surfaces.
-- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.
-- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.
-- Syntax Guard verification is still undocumented and unproven inside this repo.

scripts/README_big_brain.md

@@ -62,6 +62,24 @@ Writes:
 
 ## Usage
 
+### Timmy Mac wiring helper
+
+Use the dedicated Timmy helper when you want to wire a real RunPod or Vertex-style endpoint into the local Mac Hermes config:
+
+```bash
+python3 scripts/timmy_gemma4_mac.py --base-url https://your-openai-bridge.example/v1 --write-config
+python3 scripts/timmy_gemma4_mac.py --vertex-base-url https://your-vertex-bridge.example --write-config
+python3 scripts/timmy_gemma4_mac.py --pod-id <runpod-id> --write-config --verify-chat
+```
+
+The helper writes to `~/.hermes/config.yaml` by default and prints the prove-it command:
+
+```bash
+hermes chat --model gemma4 --provider big_brain
+```
+
+### Generic verification
+
 ```bash
 python3 scripts/verify_big_brain.py
 python3 scripts/big_brain_manager.py

scripts/timmy_gemma4_mac.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Timmy Mac Gemma 4 wiring helper for RunPod / Vertex-style Big Brain providers.
+
+Refs: timmy-home #543
+
+Safe by default:
+- computes a Big Brain base URL from an explicit URL, Vertex bridge URL, or RunPod pod id
+- can provision a RunPod pod when --apply-runpod is used and a token is available
+- can write the resolved endpoint into a Hermes config when --write-config is used
+- can verify an OpenAI-compatible chat endpoint when --verify-chat is used
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+from urllib import request
+
+from scripts.bezalel_gemma4_vps import (
+    DEFAULT_CLOUD_TYPE,
+    DEFAULT_GPU_TYPE,
+    DEFAULT_MODEL,
+    DEFAULT_PROVIDER_NAME,
+    build_runpod_endpoint,
+    deploy_runpod,
+    update_config_text,
+)
+
+DEFAULT_TOKEN_FILE = Path.home() / ".config" / "runpod" / "access_key"
+DEFAULT_CONFIG_PATH = Path.home() / ".hermes" / "config.yaml"
+
+
+def _normalize_openai_base(base_url: str | None) -> str:
+    if not base_url:
+        return ""
+    cleaned = str(base_url).strip().rstrip("/")
+    return cleaned if cleaned.endswith("/v1") else f"{cleaned}/v1"
+
+
+def choose_base_url(*, vertex_base_url: str | None = None, base_url: str | None = None, pod_id: str | None = None) -> str:
+    if vertex_base_url:
+        return _normalize_openai_base(vertex_base_url)
+    if base_url:
+        return _normalize_openai_base(base_url)
+    if pod_id:
+        return build_runpod_endpoint(pod_id)
+    return "https://YOUR_BIG_BRAIN_HOST/v1"
+
+
+def write_config_file(config_path: Path, *, base_url: str, model: str = DEFAULT_MODEL, provider_name: str = DEFAULT_PROVIDER_NAME) -> str:
+    original = config_path.read_text() if config_path.exists() else ""
+    updated = update_config_text(original, base_url=base_url, model=model, provider_name=provider_name)
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(updated)
+    return updated
+
+
+def verify_openai_chat(base_url: str, *, model: str = DEFAULT_MODEL, prompt: str = "Say READY") -> str:
+    payload = json.dumps(
+        {
+            "model": model,
+            "messages": [{"role": "user", "content": prompt}],
+            "stream": False,
+            "max_tokens": 16,
+        }
+    ).encode()
+    req = request.Request(
+        f"{base_url.rstrip('/')}/chat/completions",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with request.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read().decode())
+    return data["choices"][0]["message"]["content"]
+
+
+def build_summary(*, base_url: str, model: str, provider_name: str = DEFAULT_PROVIDER_NAME, config_path: Path = DEFAULT_CONFIG_PATH) -> dict[str, Any]:
+    return {
+        "provider_name": provider_name,
+        "base_url": base_url,
+        "model": model,
+        "config_path": str(config_path),
+        "verification_commands": [
+            "python3 scripts/verify_big_brain.py",
+            f"python3 scripts/timmy_gemma4_mac.py --base-url {base_url} --write-config --verify-chat",
+            "hermes chat --model gemma4 --provider big_brain",
+        ],
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Wire a RunPod/Vertex Gemma 4 endpoint into Timmy's Mac Hermes config.")
+    parser.add_argument("--pod-name", default="timmy-gemma4")
+    parser.add_argument("--gpu-type", default=DEFAULT_GPU_TYPE)
+    parser.add_argument("--cloud-type", default=DEFAULT_CLOUD_TYPE)
+    parser.add_argument("--model", default=DEFAULT_MODEL)
+    parser.add_argument("--provider-name", default=DEFAULT_PROVIDER_NAME)
+    parser.add_argument("--token-file", type=Path, default=DEFAULT_TOKEN_FILE)
+    parser.add_argument("--config-path", type=Path, default=DEFAULT_CONFIG_PATH)
+    parser.add_argument("--pod-id", help="Existing RunPod pod id to convert into an OpenAI-compatible base URL")
+    parser.add_argument("--base-url", help="Explicit OpenAI-compatible base URL")
+    parser.add_argument("--vertex-base-url", help="Vertex AI OpenAI-compatible bridge base URL")
+    parser.add_argument("--apply-runpod", action="store_true", help="Provision a RunPod pod using the RunPod GraphQL API")
+    parser.add_argument("--write-config", action="store_true", help="Write the resolved endpoint into --config-path")
+    parser.add_argument("--verify-chat", action="store_true", help="Run a lightweight OpenAI-compatible chat probe")
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    summary: dict[str, Any] = {
+        "pod_name": args.pod_name,
+        "gpu_type": args.gpu_type,
+        "cloud_type": args.cloud_type,
+        "model": args.model,
+        "provider_name": args.provider_name,
+        "actions": [],
+    }
+
+    base_url = choose_base_url(vertex_base_url=args.vertex_base_url, base_url=args.base_url, pod_id=args.pod_id)
+
+    if args.apply_runpod:
+        if not args.token_file.exists():
+            raise SystemExit(f"RunPod token file not found: {args.token_file}")
+        api_key = args.token_file.read_text().strip()
+        deployed = deploy_runpod(api_key=api_key, name=args.pod_name, gpu_type=args.gpu_type, cloud_type=args.cloud_type, model=args.model)
+        summary["deployment"] = deployed
+        base_url = deployed["base_url"]
+        summary["actions"].append("deployed_runpod_pod")
+
+    summary.update(build_summary(base_url=base_url, model=args.model, provider_name=args.provider_name, config_path=args.config_path))
+
+    if args.write_config:
+        write_config_file(args.config_path, base_url=base_url, model=args.model, provider_name=args.provider_name)
+        summary["actions"].append("wrote_config")
+
+    if args.verify_chat:
+        summary["verify_response"] = verify_openai_chat(base_url, model=args.model)
+        summary["actions"].append("verified_chat")
+
+    if args.json:
+        print(json.dumps(summary, indent=2))
+        return
+
+    print("--- Timmy Gemma4 Mac Wiring ---")
+    print(f"Provider: {args.provider_name}")
+    print(f"Base URL: {base_url}")
+    print(f"Model: {args.model}")
+    print(f"Config path: {args.config_path}")
+    if "verify_response" in summary:
+        print(f"Verify response: {summary['verify_response']}")
+    if summary["actions"]:
+        print("Actions: " + ", ".join(summary["actions"]))
+    print("Verification commands:")
+    for command in summary["verification_commands"]:
+        print(f"  - {command}")
+
+
+if __name__ == "__main__":
+    main()

scripts/unified_fleet_sovereignty_status.py

@@ -1,418 +0,0 @@
-#!/usr/bin/env python3
-"""Ground timmy-home #524 as an executable status report.
-
-Refs: timmy-home #524
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-from copy import deepcopy
-from pathlib import Path
-from typing import Any
-from urllib import request
-
-DEFAULT_BASE_URL = "https://forge.alexanderwhitestone.com/api/v1"
-DEFAULT_OWNER = "Timmy_Foundation"
-DEFAULT_REPO = "timmy-home"
-DEFAULT_TOKEN_FILE = Path.home() / ".config" / "gitea" / "token"
-DEFAULT_REPO_ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_DOC_PATH = DEFAULT_REPO_ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
-
-DIRECTIVE_TITLE = "[DIRECTIVE] Unified Fleet Sovereignty & Comms Migration"
-DIRECTIVE_SUMMARY = (
-    "Issue #524 is a multi-lane directive, not a one-commit feature. "
-    "This report grounds the directive in repo evidence, highlights stale cross-links, "
-    "and names the missing operator bundles that still need real execution."
-)
-
-DEFAULT_REFERENCE_SNAPSHOT = {
-    388: {
-        "title": "[KT] Fleet Lexicon & Techniques — Shared Vocabulary, Patterns, and Standards for All Agents",
-        "state": "closed",
-    },
-    103: {
-        "title": "Build comprehensive caching layer — cache everywhere",
-        "state": "open",
-    },
-    139: {
-        "title": "🐣 Allegro-Primus is born",
-        "state": "open",
-    },
-    813: {
-        "title": "docs: refresh the-playground genome analysis (#671)",
-        "state": "closed",
-    },
-    819: {
-        "title": "docs: verify #648 already implemented (closes #818)",
-        "state": "open",
-    },
-}
-
-WORKSTREAMS = [
-    {
-        "key": "nostr-migration",
-        "name": "Nostr Migration Leadership",
-        "requirement": "Replace Telegram with relay-based sovereign comms, verify wizard keypairs, and prove the NIP-29 group path is stable.",
-        "references": [813, 819],
-        "expected_keywords": ["nostr", "relay", "telegram", "comms", "messenger"],
-        "repo_evidence": [
-            {
-                "path": "infrastructure/timmy-bridge/client/timmy_client.py",
-                "description": "Nostr event client scaffold already exists",
-            },
-            {
-                "path": "infrastructure/timmy-bridge/monitor/timmy_monitor.py",
-                "description": "Nostr relay monitor already exists",
-            },
-            {
-                "path": "specs/wizard-telegram-bot-cutover.md",
-                "description": "Telegram cutover planning exists, so the migration lane is real",
-            },
-        ],
-        "missing_deliverables": [
-            "wizard keypair inventory and ownership matrix",
-            "NIP-29 relay group verification report",
-            "operator runbook for cutting traffic off Telegram",
-        ],
-        "why_open": "The repo has Nostr-adjacent scaffolding, but the directive still lacks a verified migration packet and the cited issue links drift away from the stated Nostr scope.",
-    },
-    {
-        "key": "lexicon-enforcement",
-        "name": "Lexicon Enforcement",
-        "requirement": "Enforce the Fleet Lexicon in PR review and issue triage so the team uses one shared language.",
-        "references": [388],
-        "expected_keywords": ["lexicon", "vocabulary", "standards", "shared vocabulary"],
-        "repo_evidence": [
-            {
-                "path": "docs/WIZARD_APPRENTICESHIP_CHARTER.md",
-                "description": "The repo already uses wizard-language canon in docs",
-            },
-            {
-                "path": "specs/timmy-ezra-bezalel-canon-sheet.md",
-                "description": "Canonical agent naming already exists",
-            },
-            {
-                "path": "docs/OPERATIONS_DASHBOARD.md",
-                "description": "Operational roles are already described in repo language",
-            },
-        ],
-        "missing_deliverables": [
-            "machine-checkable lexicon policy for review/triage",
-            "terminology lint or reviewer checklist tied to the lexicon",
-        ],
-        "why_open": "The naming canon exists, but there is still no executable enforcement bundle that would catch drift during future reviews and triage passes.",
-    },
-    {
-        "key": "feature-audit",
-        "name": "v0.7.0 Feature Audit",
-        "requirement": "Audit Hermes features that can reduce cloud dependency and turn the findings into a sovereignty implementation plan.",
-        "references": [139],
-        "expected_keywords": ["hermes", "feature", "audit", "v0.7.0", "sovereignty"],
-        "repo_evidence": [
-            {
-                "path": "scripts/sovereignty_audit.py",
-                "description": "Cloud-vs-local audit machinery already exists",
-            },
-            {
-                "path": "reports/evaluations/2026-04-15-phase-4-sovereignty-audit.md",
-                "description": "Recent sovereignty audit report is committed",
-            },
-            {
-                "path": "timmy-local/README.md",
-                "description": "Local-first status is already documented for operators",
-            },
-        ],
-        "missing_deliverables": [
-            "Hermes v0.7.0 feature inventory linked to cloud-reduction leverage",
-            "Sovereignty Implementation Plan derived from that feature audit",
-        ],
-        "why_open": "The repo has sovereignty-audit infrastructure, but it does not yet contain the requested v0.7.0 feature inventory or the plan that turns those findings into rollout steps.",
-    },
-    {
-        "key": "morrowind-benchmark",
-        "name": "Morrowind Local-First Benchmark",
-        "requirement": "Compare cloud and local Morrowind agents, prove local parity where possible, and document the reasoning gap when it fails.",
-        "references": [103],
-        "expected_keywords": ["morrowind", "combat", "benchmark", "local", "cloud"],
-        "repo_evidence": [
-            {
-                "path": "morrowind/local_brain.py",
-                "description": "Local Morrowind control loop already exists",
-            },
-            {
-                "path": "morrowind/mcp_server.py",
-                "description": "Morrowind MCP control surface is already wired",
-            },
-            {
-                "path": "morrowind/pilot.py",
-                "description": "Trajectory logging for evaluation already exists",
-            },
-        ],
-        "missing_deliverables": [
-            "cloud-vs-local benchmark report for the combat loop",
-            "reasoning-gap writeup tied to a proposed LoRA/fine-tune path",
-        ],
-        "why_open": "The repo has a local Morrowind stack, but it does not yet contain the requested benchmark artifact; the cited issue number also points at an unrelated caching task.",
-    },
-    {
-        "key": "syntax-guard",
-        "name": "Infrastructure Hardening / Syntax Guard",
-        "requirement": "Verify Syntax Guard pre-receive protection across Gitea repos so syntax failures stop earlier.",
-        "references": [],
-        "expected_keywords": [],
-        "repo_evidence": [],
-        "missing_deliverables": [
-            "repo inventory of Gitea targets that should carry Syntax Guard",
-            "deployment verifier for hook presence across those repos",
-            "operator report proving installation state instead of assuming it",
-        ],
-        "why_open": "No repo-managed syntax-guard verifier is present yet, so this directive still depends on manual trust rather than auditable proof.",
-    },
-]
-
-
-def default_snapshot() -> dict[int, dict[str, str]]:
-    return deepcopy(DEFAULT_REFERENCE_SNAPSHOT)
-
-
-class GiteaClient:
-    def __init__(self, token: str, owner: str = DEFAULT_OWNER, repo: str = DEFAULT_REPO, base_url: str = DEFAULT_BASE_URL):
-        self.token = token
-        self.owner = owner
-        self.repo = repo
-        self.base_url = base_url.rstrip("/")
-
-    def get_issue(self, issue_number: int) -> dict[str, Any]:
-        req = request.Request(
-            f"{self.base_url}/repos/{self.owner}/{self.repo}/issues/{issue_number}",
-            headers={"Authorization": f"token {self.token}", "Accept": "application/json"},
-        )
-        with request.urlopen(req, timeout=30) as resp:
-            return json.loads(resp.read().decode())
-
-
-def load_snapshot(path: Path | None = None) -> dict[int, dict[str, str]]:
-    if path is None:
-        return default_snapshot()
-    data = json.loads(path.read_text(encoding="utf-8"))
-    return {int(k): v for k, v in data.items()}
-
-
-def refresh_snapshot(token_file: Path = DEFAULT_TOKEN_FILE) -> dict[int, dict[str, str]]:
-    token = token_file.read_text(encoding="utf-8").strip()
-    client = GiteaClient(token=token)
-    snapshot: dict[int, dict[str, str]] = {}
-    for issue_number in sorted(DEFAULT_REFERENCE_SNAPSHOT):
-        issue = client.get_issue(issue_number)
-        snapshot[issue_number] = {
-            "title": issue["title"],
-            "state": issue["state"],
-        }
-    return snapshot
-
-
-def collect_repo_evidence(entries: list[dict[str, str]], repo_root: Path) -> tuple[list[str], list[str]]:
-    present: list[str] = []
-    missing: list[str] = []
-    for entry in entries:
-        label = f"`{entry['path']}` — {entry['description']}"
-        if (repo_root / entry["path"]).exists():
-            present.append(label)
-        else:
-            missing.append(label)
-    return present, missing
-
-
-
-def evaluate_reference(issue_number: int, snapshot: dict[int, dict[str, str]], expected_keywords: list[str]) -> dict[str, Any]:
-    record = snapshot.get(issue_number, {"title": "missing from snapshot", "state": "unknown"})
-    title = record["title"]
-    title_lower = title.lower()
-    matched_keywords = [kw for kw in expected_keywords if kw.lower() in title_lower]
-    aligned = bool(matched_keywords) if expected_keywords else True
-    return {
-        "number": issue_number,
-        "title": title,
-        "state": record["state"],
-        "aligned": aligned,
-        "matched_keywords": matched_keywords,
-    }
-
-
-
-def classify_workstream(reference_results: list[dict[str, Any]], evidence_present: list[str], missing_deliverables: list[str]) -> str:
-    has_drift = any(not item["aligned"] for item in reference_results)
-    if not evidence_present:
-        return "MISSING"
-    if has_drift or missing_deliverables:
-        return "PARTIAL"
-    return "GROUNDED"
-
-
-
-def evaluate_directive(snapshot: dict[int, dict[str, str]] | None = None, repo_root: Path | None = None) -> dict[str, Any]:
-    snapshot = snapshot or default_snapshot()
-    repo_root = repo_root or DEFAULT_REPO_ROOT
-    workstreams: list[dict[str, Any]] = []
-    drift_items: list[str] = []
-
-    for lane in WORKSTREAMS:
-        reference_results = [
-            evaluate_reference(issue_number, snapshot, lane["expected_keywords"])
-            for issue_number in lane["references"]
-        ]
-        present, missing = collect_repo_evidence(lane["repo_evidence"], repo_root)
-        for item in reference_results:
-            if not item["aligned"]:
-                drift_items.append(
-                    f"#{item['number']} is cited for {lane['name']}, but its current title is '{item['title']}'."
-                )
-        workstream = {
-            "key": lane["key"],
-            "name": lane["name"],
-            "requirement": lane["requirement"],
-            "reference_results": reference_results,
-            "repo_evidence_present": present,
-            "repo_evidence_missing": missing,
-            "missing_deliverables": list(lane["missing_deliverables"]),
-            "why_open": lane["why_open"],
-        }
-        workstream["status"] = classify_workstream(
-            reference_results=reference_results,
-            evidence_present=present,
-            missing_deliverables=workstream["missing_deliverables"],
-        )
-        workstreams.append(workstream)
-
-    next_actions: list[str] = []
-    for workstream in workstreams:
-        if workstream["missing_deliverables"]:
-            next_actions.append(f"{workstream['name']}: {workstream['missing_deliverables'][0]}")
-
-    return {
-        "issue_number": 524,
-        "title": DIRECTIVE_TITLE,
-        "summary": DIRECTIVE_SUMMARY,
-        "reference_snapshot": {str(k): v for k, v in sorted(snapshot.items())},
-        "workstreams": workstreams,
-        "reference_drift": drift_items,
-        "grounded_workstreams": sum(1 for item in workstreams if item["status"] == "GROUNDED"),
-        "partial_workstreams": sum(1 for item in workstreams if item["status"] == "PARTIAL"),
-        "missing_workstreams": sum(1 for item in workstreams if item["status"] == "MISSING"),
-        "next_actions": next_actions,
-    }
-
-
-
-def render_markdown(result: dict[str, Any]) -> str:
-    lines = [
-        f"# {result['title']}",
-        "",
-        "Grounding report for `timmy-home #524`.",
-        "",
-        result["summary"],
-        "",
-        "This remains a `Refs #524` artifact. The directive spans multiple repos and operator actions, so this report makes the current repo-side state executable without pretending the whole migration is complete.",
-        "",
-        "## Directive Snapshot",
-        "",
-        f"- Repo-grounded workstreams: {result['grounded_workstreams']}",
-        f"- Partial workstreams: {result['partial_workstreams']}",
-        f"- Missing workstreams: {result['missing_workstreams']}",
-        f"- Drifted references: {len(result['reference_drift'])}",
-        "",
-        "## Reference Drift",
-        "",
-    ]
-    if result["reference_drift"]:
-        lines.extend(f"- {item}" for item in result["reference_drift"])
-    else:
-        lines.append("- No stale cross-links detected in the directive snapshot.")
-
-    lines.extend(["", "## Workstream Matrix", ""])
-    for index, workstream in enumerate(result["workstreams"], start=1):
-        lines.extend(
-            [
-                f"### {index}. {workstream['name']} — {workstream['status']}",
-                "",
-                f"- Requirement: {workstream['requirement']}",
-            ]
-        )
-        if workstream["reference_results"]:
-            lines.append("- Referenced issues:")
-            for ref in workstream["reference_results"]:
-                alignment = "aligned" if ref["aligned"] else "DRIFT"
-                lines.append(
-                    f"  - #{ref['number']} ({ref['state']}) — {ref['title']} [{alignment}]"
-                )
-        else:
-            lines.append("- Referenced issues: none listed in the directive body")
-
-        if workstream["repo_evidence_present"]:
-            lines.append("- Repo evidence present:")
-            lines.extend(f"  - {item}" for item in workstream["repo_evidence_present"])
-        else:
-            lines.append("- Repo evidence present: none")
-
-        if workstream["repo_evidence_missing"]:
-            lines.append("- Repo evidence expected but missing:")
-            lines.extend(f"  - {item}" for item in workstream["repo_evidence_missing"])
-
-        if workstream["missing_deliverables"]:
-            lines.append("- Missing operator deliverables:")
-            lines.extend(f"  - {item}" for item in workstream["missing_deliverables"])
-        else:
-            lines.append("- Missing operator deliverables: none")
-
-        lines.append(f"- Why this lane remains open: {workstream['why_open']}")
-        lines.append("")
-
-    lines.extend(["## Highest-Leverage Next Actions", ""])
-    lines.extend(f"- {item}" for item in result["next_actions"])
-
-    lines.extend(
-        [
-            "",
-            "## Why #524 Remains Open",
-            "",
-            "- The directive bundles five separate workstreams with different evidence surfaces.",
-            "- Multiple cited issue numbers have drifted away from the work they are supposed to anchor.",
-            "- Repo scaffolding exists for Nostr, sovereignty audits, and Morrowind, but the operator-facing bundles are still missing.",
-            "- Syntax Guard verification is still undocumented and unproven inside this repo.",
-        ]
-    )
-
-    return "\n".join(lines).rstrip() + "\n"
-
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Render the unified fleet sovereignty status report for issue #524")
-    parser.add_argument("--snapshot", help="Optional JSON snapshot file overriding the default issue-title/state snapshot")
-    parser.add_argument("--live", action="store_true", help="Refresh the issue snapshot from Gitea before rendering")
-    parser.add_argument("--token-file", default=str(DEFAULT_TOKEN_FILE), help="Token file used with --live")
-    parser.add_argument("--output", help="Optional path to write the rendered report")
-    parser.add_argument("--json", action="store_true", help="Print computed JSON instead of markdown")
-    args = parser.parse_args()
-
-    if args.live:
-        snapshot = refresh_snapshot(Path(args.token_file).expanduser())
-    else:
-        snapshot = load_snapshot(Path(args.snapshot).expanduser() if args.snapshot else None)
-
-    result = evaluate_directive(snapshot=snapshot, repo_root=DEFAULT_REPO_ROOT)
-    rendered = json.dumps(result, indent=2) if args.json else render_markdown(result)
-
-    if args.output:
-        output_path = Path(args.output).expanduser()
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        output_path.write_text(rendered, encoding="utf-8")
-        print(f"Directive status written to {output_path}")
-    else:
-        print(rendered)
-
-
-if __name__ == "__main__":
-    main()

tests/test_timmy_gemma4_mac.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = ROOT / "scripts" / "timmy_gemma4_mac.py"
+README = ROOT / "scripts" / "README_big_brain.md"
+
+
+def load_module():
+    spec = importlib.util.spec_from_file_location("timmy_gemma4_mac", str(SCRIPT))
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules["timmy_gemma4_mac"] = mod
+    spec.loader.exec_module(mod)
+    return mod
+
+
+class _FakeResponse:
+    def __init__(self, payload: dict):
+        self._payload = json.dumps(payload).encode()
+
+    def read(self) -> bytes:
+        return self._payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        return False
+
+
+def test_script_exists() -> None:
+    assert SCRIPT.exists(), "scripts/timmy_gemma4_mac.py must exist"
+
+
+def test_default_paths_target_timmy_mac_hermes() -> None:
+    mod = load_module()
+    assert mod.DEFAULT_CONFIG_PATH == Path.home() / ".hermes" / "config.yaml"
+    assert mod.DEFAULT_TOKEN_FILE == Path.home() / ".config" / "runpod" / "access_key"
+
+
+def test_choose_base_url_prefers_vertex_then_explicit_then_runpod() -> None:
+    mod = load_module()
+    assert mod.choose_base_url(vertex_base_url="https://vertex-proxy.example/v1") == "https://vertex-proxy.example/v1"
+    assert mod.choose_base_url(base_url="https://custom-endpoint/v1") == "https://custom-endpoint/v1"
+    assert mod.choose_base_url(pod_id="abc123") == "https://abc123-11434.proxy.runpod.net/v1"
+
+
+def test_build_summary_includes_prove_it_commands() -> None:
+    mod = load_module()
+    summary = mod.build_summary(base_url="https://vertex-proxy.example/v1", model="gemma4:latest")
+    assert summary["verification_commands"][0] == "python3 scripts/verify_big_brain.py"
+    assert any("hermes chat --model gemma4 --provider big_brain" in cmd for cmd in summary["verification_commands"])
+
+
+def test_verify_openai_chat_targets_chat_completions() -> None:
+    mod = load_module()
+    response_payload = {
+        "choices": [{"message": {"content": "READY"}}]
+    }
+
+    with patch("timmy_gemma4_mac.request.urlopen", return_value=_FakeResponse(response_payload)) as mocked:
+        result = mod.verify_openai_chat("https://vertex-proxy.example/v1", model="gemma4:latest", prompt="say READY")
+
+    assert result == "READY"
+    req = mocked.call_args.args[0]
+    assert req.full_url == "https://vertex-proxy.example/v1/chat/completions"
+
+
+def test_readme_mentions_timmy_mac_wiring_flow() -> None:
+    text = README.read_text(encoding="utf-8")
+    required = [
+        "scripts/timmy_gemma4_mac.py",
+        "--vertex-base-url",
+        "--write-config",
+        "python3 scripts/verify_big_brain.py",
+        "hermes chat --model gemma4 --provider big_brain",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing

tests/test_unified_fleet_sovereignty_status.py

@@ -1,77 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[1]
-SCRIPT_PATH = ROOT / "scripts" / "unified_fleet_sovereignty_status.py"
-DOC_PATH = ROOT / "docs" / "UNIFIED_FLEET_SOVEREIGNTY_STATUS.md"
-
-
-def _load_module(path: Path, name: str):
-    assert path.exists(), f"missing {path.relative_to(ROOT)}"
-    spec = importlib.util.spec_from_file_location(name, path)
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def _workstream(result: dict, key: str) -> dict:
-    for workstream in result["workstreams"]:
-        if workstream["key"] == key:
-            return workstream
-    raise AssertionError(f"missing workstream {key}")
-
-
-def test_evaluate_directive_flags_reference_drift_without_faking_completion() -> None:
-    mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
-    result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
-
-    assert len(result["reference_drift"]) == 4
-    assert any("#813" in item for item in result["reference_drift"])
-    assert any("#103" in item for item in result["reference_drift"])
-
-    nostr = _workstream(result, "nostr-migration")
-    assert nostr["status"] == "PARTIAL"
-    assert any("timmy_client.py" in item for item in nostr["repo_evidence_present"])
-
-    lexicon = _workstream(result, "lexicon-enforcement")
-    assert all(item["aligned"] for item in lexicon["reference_results"])
-    assert lexicon["status"] == "PARTIAL"
-
-    syntax_guard = _workstream(result, "syntax-guard")
-    assert syntax_guard["status"] == "MISSING"
-    assert any("deployment verifier" in item for item in syntax_guard["missing_deliverables"])
-
-
-def test_render_markdown_includes_required_sections_and_grounding_evidence() -> None:
-    mod = _load_module(SCRIPT_PATH, "unified_fleet_sovereignty_status")
-    result = mod.evaluate_directive(snapshot=mod.default_snapshot(), repo_root=ROOT)
-    report = mod.render_markdown(result)
-
-    for snippet in (
-        "# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
-        "## Directive Snapshot",
-        "## Reference Drift",
-        "## Workstream Matrix",
-        "### 5. Infrastructure Hardening / Syntax Guard — MISSING",
-        "`infrastructure/timmy-bridge/client/timmy_client.py`",
-        "machine-checkable lexicon policy for review/triage",
-        "## Why #524 Remains Open",
-    ):
-        assert snippet in report
-
-
-def test_repo_contains_committed_issue_524_grounding_doc() -> None:
-    assert DOC_PATH.exists(), "missing committed directive grounding doc"
-    text = DOC_PATH.read_text(encoding="utf-8")
-    for snippet in (
-        "# [DIRECTIVE] Unified Fleet Sovereignty & Comms Migration",
-        "## Reference Drift",
-        "## Workstream Matrix",
-        "## Highest-Leverage Next Actions",
-        "## Why #524 Remains Open",
-    ):
-        assert snippet in text