the-nexus/scripts/zero_touch_forge_readiness.py

#!/usr/bin/env python3
"""Zero-Touch Forge readiness grounding for epic #912.

This does not pretend the impossible goal is solved.
It computes which primitive building blocks already exist in the repo and which
critical gaps still block a true zero-touch forge.
"""

from __future__ import annotations

import argparse
import json
from pathlib import Path
from typing import Any

REPO_ROOT = Path(__file__).resolve().parent.parent
SPEC_PATH = REPO_ROOT / "config" / "zero_touch_forge.json"


def load_spec(path: Path | None = None) -> dict[str, Any]:
    target = path or SPEC_PATH
    return json.loads(target.read_text())


def _file_exists_map(repo_root: Path, paths: list[str]) -> dict[str, bool]:
    return {path: (repo_root / path).exists() for path in paths}


def _agent_count(repo_root: Path) -> int:
    config_path = repo_root / "config" / "fleet_agents.json"
    if not config_path.exists():
        return 0
    try:
        payload = json.loads(config_path.read_text())
        return len(payload.get("agents") or [])
    except Exception:
        return 0


def derive_signal_flags(repo_root: Path | None = None) -> dict[str, bool]:
    root = repo_root or REPO_ROOT
    agent_count = _agent_count(root)
    return {
        "has_age_seed_flow": False,
        "has_crypto_integrity_verification": False,
        "has_stack_start_manifest": agent_count >= 5,
        "has_test_gate": False,
        "has_notification_step": False,
        "has_sla_budget": False,
    }


def _evidence_line(check: dict[str, Any], file_exists: dict[str, bool], signal_flags: dict[str, bool]) -> str:
    parts = []
    for path in check.get("required_files", []):
        parts.append(f"{path}={'present' if file_exists.get(path) else 'missing'}")
    for key in check.get("required_signals", []):
        parts.append(f"{key}={'yes' if signal_flags.get(key) else 'no'}")
    return ", ".join(parts) if parts else "no explicit evidence"


def evaluate_readiness(
    spec: dict[str, Any],
    *,
    file_exists: dict[str, bool] | None = None,
    signal_flags: dict[str, bool] | None = None,
) -> dict[str, Any]:
    all_paths = []
    for check in spec["checks"]:
        all_paths.extend(check.get("required_files", []))

    file_exists = file_exists or _file_exists_map(REPO_ROOT, sorted(set(all_paths)))
    signal_flags = signal_flags or derive_signal_flags(REPO_ROOT)

    ready_checks = []
    blocked_checks = []
    checks = []

    for check in spec["checks"]:
        missing_files = [path for path in check.get("required_files", []) if not file_exists.get(path, False)]
        missing_signals = [key for key in check.get("required_signals", []) if not signal_flags.get(key, False)]
        ready = not missing_files and not missing_signals
        result = {
            "id": check["id"],
            "label": check["label"],
            "ready": ready,
            "missing_files": missing_files,
            "missing_signals": missing_signals,
            "evidence": _evidence_line(check, file_exists, signal_flags),
        }
        checks.append(result)
        if ready:
            ready_checks.append(result)
        else:
            blocked_checks.append(result)

    return {
        "epic_issue": spec["epic_issue"],
        "title": spec["title"],
        "ready_count": len(ready_checks),
        "blocked_count": len(blocked_checks),
        "ready_checks": ready_checks,
        "blocked_checks": blocked_checks,
        "checks": checks,
        "signals": signal_flags,
        "files": file_exists,
    }


def render_markdown(report: dict[str, Any]) -> str:
    lines = [
        "# Zero-Touch Forge Readiness",
        "",
        f"Epic: #{report['epic_issue']} — {report['title']}",
        "",
        "## Impossible Goal",
        "",
        "Take a raw VPS plus only a git URL and encrypted seed, then bootstrap a full Timmy Foundation fleet in under 60 minutes with no human intervention after trigger.",
        "",
        "This document does **not** claim the goal is solved. It grounds the epic in the current repo state.",
        "",
        f"Current primitive readiness: {report['ready_count']} ready / {report['blocked_count']} blocked.",
        "",
        "## Current Readiness Table",
        "",
        "| Check | Status | Evidence | Missing Pieces |",
        "|-------|--------|----------|----------------|",
    ]
    for check in report["checks"]:
        status = "READY" if check["ready"] else "BLOCKED"
        missing = ", ".join(check["missing_files"] + check["missing_signals"]) or "—"
        lines.append(f"| {check['label']} | {status} | {check['evidence']} | {missing} |")

    lines.extend([
        "",
        "## Interpretation",
        "",
        "### What already exists",
        "- `scripts/provision-runner.sh` proves we already automate part of bare-metal service bootstrap.",
        "- `scripts/lazarus_checkpoint.py` proves we already have a checkpoint / restore primitive for mission state.",
        "- `docker-compose.yml`, `fleet/fleet-routing.json`, `operations/fleet-topology.md`, and `config/fleet_agents.json` show a real fleet shape, not just a philosophical wish.",
        "",
        "### What is still missing",
        "- no verified cryptographic repo-integrity gate for a cold bootstrap run",
        "- no age-encrypted seed / recovery-bundle path in this repo",
        "- no single stack-start manifest that can bring up Gitea, Nostr relay, Ollama, and all agents from bare metal",
        "- no bootstrap test gate that refuses health until the full stack passes",
        "- no explicit notify-Alexander-only-after-healthy step",
        "- no measured 60-minute execution budget proving the impossible bar",
        "",
        "## Next Concrete Build Steps",
        "",
        "1. Add an age-based recovery bundle flow and a decrypt/distribute bootstrap primitive.",
        "2. Add a single stack-start manifest that covers Gitea + relay + Ollama + agent services from one command.",
        "3. Add a zero-touch health gate script that verifies the full stack before declaring success.",
        "4. Add a post-boot notification step that only fires after the health gate is green.",
        "5. Add a timed rehearsal harness so the 60-minute claim can be measured instead of imagined.",
        "",
        "## Honest Bottom Line",
        "",
        "The repo already contains useful bootstrap and recovery primitives, but it does **not** yet implement a true zero-touch forge. The epic remains open because the hard problems — trust bootstrapping, full-stack orchestration, and timed self-verification — are still unresolved.",
        "",
    ])
    return "\n".join(lines)


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Evaluate repo readiness for the Zero-Touch Forge epic.")
    parser.add_argument("--json", action="store_true", help="Emit JSON instead of markdown")
    parser.add_argument("--out", type=Path, help="Optional output file")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    spec = load_spec()
    report = evaluate_readiness(spec)
    output = json.dumps(report, indent=2) if args.json else render_markdown(report)
    if args.out:
        args.out.parent.mkdir(parents=True, exist_ok=True)
        args.out.write_text(output)
    else:
        print(output)


if __name__ == "__main__":
    main()