Compare commits

..

1 Commits

Author SHA1 Message Date
Timmy Agent
2f53409614 feat(lab-005): Deploy AI agent fleet on available laptops (#530)
Some checks failed
Self-Healing Smoke / self-healing-smoke (pull_request) Failing after 27s
Smoke Test / smoke (pull_request) Failing after 29s
Agent PR Gate / gate (pull_request) Failing after 49s
Agent PR Gate / report (pull_request) Successful in 17s
- Add configs/laptop-fleet-manifest.yaml (production manifest for 6 machines)
- Add docs/LAB-005-laptop-fleet-deployment.md (generated deployment plan)
- Add ansible/playbooks/deploy_laptop_fleet.yml (Ansible playbook for Linux laptops)
- Add ansible/inventory/laptops.ini (fleet inventory with role groups)
- Add configs/hermes-laptop-anchor.service (24/7 systemd user service)
- Add configs/hermes-laptop-daylight.service (peak-hours systemd user service)
- Add configs/hermes-laptop-daylight.timer (systemd timer for 10:00 start)
- Expand tests to verify production manifest, plan, playbook, and services
2026-04-22 01:48:33 -04:00
11 changed files with 341 additions and 602 deletions

View File

@@ -0,0 +1,27 @@
[laptop_anchor]
# 24/7 anchor agents — lowest idle wattage, reliable adapters
timmy-anchor-a ansible_host=TIMMY_ANCHOR_A_IP ansible_user=timmy
[laptop_daylight]
# Daylight compute nodes — peak solar hours only
timmy-daylight-a ansible_host=TIMMY_DAYLIGHT_A_IP ansible_user=timmy
timmy-daylight-b ansible_host=TIMMY_DAYLIGHT_B_IP ansible_user=timmy
[laptop_pending]
# Machines awaiting hardware repair before production duty
timmy-daylight-c ansible_host=TIMMY_DAYLIGHT_C_IP ansible_user=timmy
[desktop_nas]
# Heavy compute + 4TB SSD NAS — daylight only due to power draw
timmy-desktop-nas ansible_host=TIMMY_DESKTOP_NAS_IP ansible_user=timmy
[laptops:children]
laptop_anchor
laptop_daylight
laptop_pending
desktop_nas
[laptops:vars]
ansible_python_interpreter=/usr/bin/python3
timmy_home=/home/timmy/timmy
timmy_repo=https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home.git

View File

@@ -0,0 +1,137 @@
---
- name: Deploy Hermes agent fleet on available laptops
hosts: laptops
gather_facts: true
vars:
timmy_user: "{{ ansible_user }}"
timmy_dir: "/home/{{ timmy_user }}/timmy"
hermes_repo: "https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home.git"
hermes_agent_repo: "https://forge.alexanderwhitestone.com/Timmy_Foundation/hermes-agent.git"
tasks:
- name: Ensure required packages are installed
ansible.builtin.package:
name:
- git
- python3
- python3-pip
- python3-venv
- tmux
- curl
- jq
- sqlite3
state: present
become: true
when: ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
- name: Ensure timmy directory exists
ansible.builtin.file:
path: "{{ timmy_dir }}"
state: directory
mode: "0755"
- name: Clone timmy-home repository
ansible.builtin.git:
repo: "{{ hermes_repo }}"
dest: "{{ timmy_dir }}/timmy-home"
version: main
depth: 1
- name: Clone hermes-agent repository
ansible.builtin.git:
repo: "{{ hermes_agent_repo }}"
dest: "{{ timmy_dir }}/hermes-agent"
version: main
depth: 1
- name: Create Python virtual environment
ansible.builtin.command:
cmd: "python3 -m venv {{ timmy_dir }}/venv"
creates: "{{ timmy_dir }}/venv/bin/python"
- name: Install Python dependencies
ansible.builtin.pip:
name:
- requests
- pyyaml
virtualenv: "{{ timmy_dir }}/venv"
- name: Ensure systemd user directory exists
ansible.builtin.file:
path: "{{ ansible_env.HOME | default('/home/' + timmy_user) }}/.config/systemd/user"
state: directory
mode: "0755"
when: ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
- name: Deploy anchor agent systemd user service
ansible.builtin.template:
src: "../../configs/hermes-laptop-anchor.service"
dest: "{{ ansible_env.HOME | default('/home/' + timmy_user) }}/.config/systemd/user/hermes-laptop-anchor.service"
mode: "0644"
when:
- inventory_hostname in groups['laptop_anchor']
- ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
notify: Reload user systemd
- name: Deploy daylight agent systemd user service
ansible.builtin.template:
src: "../../configs/hermes-laptop-daylight.service"
dest: "{{ ansible_env.HOME | default('/home/' + timmy_user) }}/.config/systemd/user/hermes-laptop-daylight.service"
mode: "0644"
when:
- inventory_hostname in groups['laptop_daylight']
- ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
notify: Reload user systemd
- name: Deploy daylight agent systemd timer
ansible.builtin.template:
src: "../../configs/hermes-laptop-daylight.timer"
dest: "{{ ansible_env.HOME | default('/home/' + timmy_user) }}/.config/systemd/user/hermes-laptop-daylight.timer"
mode: "0644"
when:
- inventory_hostname in groups['laptop_daylight']
- ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
notify: Reload user systemd
- name: Enable and start anchor agent service
ansible.builtin.systemd:
name: hermes-laptop-anchor.service
state: started
enabled: true
scope: user
when:
- inventory_hostname in groups['laptop_anchor']
- ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
- name: Enable daylight agent timer
ansible.builtin.systemd:
name: hermes-laptop-daylight.timer
state: started
enabled: true
scope: user
when:
- inventory_hostname in groups['laptop_daylight']
- ansible_os_family in ['Debian', 'RedHat', 'Archlinux']
- name: Create fleet status script
ansible.builtin.copy:
dest: "{{ timmy_dir }}/scripts/status.sh"
content: |
#!/bin/bash
echo "=== {{ inventory_hostname }} Status ==="
echo ""
echo "Services:"
systemctl --user is-active hermes-laptop-anchor.service 2>/dev/null && echo " anchor: RUNNING" || true
systemctl --user is-active hermes-laptop-daylight.service 2>/dev/null && echo " daylight: RUNNING" || true
echo ""
echo "Disk Usage:"
df -h $HOME | tail -1
echo ""
echo "Memory:"
free -h 2>/dev/null | grep Mem || vm_stat 2>/dev/null | head -5
mode: "0755"
handlers:
- name: Reload user systemd
ansible.builtin.command: systemctl --user daemon-reload
changed_when: true

View File

@@ -0,0 +1,15 @@
[Unit]
Description=Hermes Laptop Anchor Agent (24/7)
After=network.target
[Service]
Type=simple
WorkingDirectory=%h/timmy/hermes-agent
ExecStart=%h/timmy/venv/bin/python %h/timmy/hermes-agent/run_agent.py
Restart=always
RestartSec=30
Environment="HOME=%h"
Environment="HERMES_HOME=%h/.hermes"
[Install]
WantedBy=default.target

View File

@@ -0,0 +1,16 @@
[Unit]
Description=Hermes Laptop Daylight Agent
After=network.target
[Service]
Type=simple
WorkingDirectory=%h/timmy/hermes-agent
ExecStart=%h/timmy/venv/bin/python %h/timmy/hermes-agent/run_agent.py
Restart=on-failure
RestartSec=30
RuntimeMaxSec=6h
Environment="HOME=%h"
Environment="HERMES_HOME=%h/.hermes"
[Install]
WantedBy=default.target

View File

@@ -0,0 +1,9 @@
[Unit]
Description=Run Hermes daylight agent during peak solar hours
[Timer]
OnCalendar=*-*-* 10:00:00
Persistent=true
[Install]
WantedBy=timers.target

View File

@@ -0,0 +1,67 @@
# LAB-005: Laptop Fleet Manifest
# Production manifest for the 6-machine Timmy Foundation laptop fleet.
# Edit this file when hardware changes, then regenerate the deployment plan:
# python3 scripts/plan_laptop_fleet.py configs/laptop-fleet-manifest.yaml --markdown > docs/LAB-005-laptop-fleet-deployment.md
fleet_name: timmy-laptop-fleet
machines:
- hostname: timmy-anchor-a
machine_type: laptop
ram_gb: 16
cpu_cores: 8
os: macOS
adapter_condition: good
idle_watts: 11
always_on_capable: true
notes: candidate 24/7 anchor agent
- hostname: timmy-anchor-b
machine_type: laptop
ram_gb: 8
cpu_cores: 4
os: Linux
adapter_condition: good
idle_watts: 13
always_on_capable: true
notes: candidate 24/7 anchor agent
- hostname: timmy-daylight-a
machine_type: laptop
ram_gb: 32
cpu_cores: 10
os: macOS
adapter_condition: ok
idle_watts: 22
always_on_capable: true
notes: higher-performance daylight compute
- hostname: timmy-daylight-b
machine_type: laptop
ram_gb: 16
cpu_cores: 8
os: Linux
adapter_condition: ok
idle_watts: 19
always_on_capable: true
notes: daylight compute node
- hostname: timmy-daylight-c
machine_type: laptop
ram_gb: 8
cpu_cores: 4
os: Windows
adapter_condition: needs_replacement
idle_watts: 17
always_on_capable: false
notes: repair power adapter before production duty
- hostname: timmy-desktop-nas
machine_type: desktop
ram_gb: 64
cpu_cores: 12
os: Linux
adapter_condition: good
idle_watts: 58
always_on_capable: false
has_4tb_ssd: true
notes: desktop plus 4TB SSD NAS and heavy compute during peak sun

View File

@@ -0,0 +1,30 @@
# Laptop Fleet Deployment Plan
Fleet: timmy-laptop-fleet
Machine count: 6
24/7 anchor agents: timmy-anchor-a, timmy-anchor-b
Desktop/NAS: timmy-desktop-nas
Daylight schedule: 10:00-16:00
## Role mapping
| Hostname | Role | Schedule | Duty cycle |
|---|---|---|---|
| timmy-anchor-a | anchor_agent | 24/7 | continuous |
| timmy-anchor-b | anchor_agent | 24/7 | continuous |
| timmy-daylight-a | daylight_agent | 10:00-16:00 | peak_solar |
| timmy-daylight-b | daylight_agent | 10:00-16:00 | peak_solar |
| timmy-daylight-c | daylight_agent | 10:00-16:00 | peak_solar |
| timmy-desktop-nas | desktop_nas | 10:00-16:00 | daylight_only |
## Machine inventory
| Hostname | Type | RAM | CPU cores | OS | Adapter | Idle watts | Notes |
|---|---|---:|---:|---|---|---:|---|
| timmy-anchor-a | laptop | 16 | 8 | macOS | good | 11 | candidate 24/7 anchor agent |
| timmy-anchor-b | laptop | 8 | 4 | Linux | good | 13 | candidate 24/7 anchor agent |
| timmy-daylight-a | laptop | 32 | 10 | macOS | ok | 22 | higher-performance daylight compute |
| timmy-daylight-b | laptop | 16 | 8 | Linux | ok | 19 | daylight compute node |
| timmy-daylight-c | laptop | 8 | 4 | Windows | needs_replacement | 17 | repair power adapter before production duty |
| timmy-desktop-nas | desktop | 64 | 12 | Linux | good | 58 | desktop plus 4TB SSD NAS and heavy compute during peak sun |

View File

@@ -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.

View File

@@ -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()

View File

@@ -50,3 +50,43 @@ def test_manifest_template_is_valid_yaml() -> None:
data = yaml.safe_load(Path("docs/laptop-fleet-manifest.example.yaml").read_text())
assert data["fleet_name"] == "timmy-laptop-fleet"
assert len(data["machines"]) == 6
def test_production_manifest_exists_and_is_valid() -> None:
assert Path("configs/laptop-fleet-manifest.yaml").exists()
data = yaml.safe_load(Path("configs/laptop-fleet-manifest.yaml").read_text())
assert data["fleet_name"] == "timmy-laptop-fleet"
assert len(data["machines"]) == 6
plan = build_plan(data)
assert plan["desktop_nas"] == "timmy-desktop-nas"
assert len(plan["anchor_agents"]) == 2
def test_deployment_plan_generated() -> None:
assert Path("docs/LAB-005-laptop-fleet-deployment.md").exists()
content = Path("docs/LAB-005-laptop-fleet-deployment.md").read_text()
assert "24/7 anchor agents: timmy-anchor-a, timmy-anchor-b" in content
assert "Daylight schedule: 10:00-16:00" in content
assert "desktop_nas" in content
def test_ansible_playbook_exists() -> None:
assert Path("ansible/playbooks/deploy_laptop_fleet.yml").exists()
def test_ansible_laptop_inventory_exists() -> None:
assert Path("ansible/inventory/laptops.ini").exists()
content = Path("ansible/inventory/laptops.ini").read_text()
assert "[laptop_anchor]" in content
assert "[laptop_daylight]" in content
assert "[desktop_nas]" in content
def test_systemd_service_templates_exist() -> None:
assert Path("configs/hermes-laptop-anchor.service").exists()
assert Path("configs/hermes-laptop-daylight.service").exists()
assert Path("configs/hermes-laptop-daylight.timer").exists()
anchor = Path("configs/hermes-laptop-anchor.service").read_text()
daylight = Path("configs/hermes-laptop-daylight.service").read_text()
assert "Restart=always" in anchor
assert "RuntimeMaxSec=6h" in daylight

View File

@@ -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