Skip to content

Making-of journal

A living record of how this repo came together. Append new chapters at the bottom; never rewrite history — if something changes, add a new chapter that says so.

Chapter 1 — the council decision and the initial blueprint (2026-07-07)

A three-model council (Codex chairing synthesis, gpt-oss:120b, qwen3-coder:30b) was asked whether a 4-PC home lab (Windows 11, Docker Desktop, no always-on Linux server, churning DHCP, one isolated subnet island) should run Kubernetes for DR/orchestration of claude-mem (stateful Postgres+Valkey+worker), the GitHub-Actions self-hosted runner pool, and future stateless daemons.

The verdict was unanimous: full Kubernetes is overkill and fragile for this environment specifically (not a general k8s critique — see the framing in how-we-got-here.md). The recommendation: fix addressing first (foundation/), run Docker Compose declared in Git as the baseline, harden a bespoke pg_dump warm-standby DR loop with a tested promote/restore-verify/primary-marker sequence, keep Docker Swarm as an optional later step for stateless workloads only, and keep the GitHub-Actions runner out of every cluster (GitHub is already its scheduler/HA layer, and one job needs Windows/DPAPI anyway).

That session produced the full first pass of this repo: the four docs (docs/README.md, how-we-got-here.md, pros-cons.md, when-to-graduate.md, MIGRATION-PATH.md), the foundation/ addressing scripts, the compose/ recommended path (stacks + the four DR scripts + optional Swarm variant), and the kubernetes/ learning lab (k3s scripts + manifests + runbook), all explicitly labeled learning-not-production throughout. One bug shipped in that pass and was caught and fixed during test-writing (see Chapter 2).

Chapter 2 — bringing the repo up to the house tool-repo standard (2026-07-08)

The blueprint existed but had no docs set beyond docs/, no tests, no CI, and no root README.md. This chapter closes that gap:

  • Root README.md, TESTING.md, docs/technical/ARCHITECTURE.md (Mermaid component + sequence diagrams), docs/plain/README.md, docs/technical/SECURITY.md, this journal, and docs/BOARD.md.
  • A real Pester 5+ test suite (tests/) covering every PowerShell script: AST parse-cleanliness, a repo-wide secret-shaped-literal grep, structural conventions (SupportsShouldProcess, # REQUIRES REAL HARDWARE banners), and — where genuinely possible without Docker/elevation/WSL-SSH/real hardware — actual hermetic -WhatIf invocations (not just parsing) so Pester's code-coverage tracer can credit real execution. Two scripts (Test-NodeResolution.ps1, Set-PrimaryMarker.ps1 -Action Get) call exit unconditionally and are instead run as a real child process, which is safe but earns no coverage credit — documented honestly in TESTING.md.
  • A markdown link-checker (tests/MarkdownLinks.Tests.ps1) — the practical "test layer" for a docs-heavy blueprint: every relative link across every .md file must resolve to a real file.
  • Manifest/compose structural sanity checks (tests/Manifests.Tests.ps1) — no tabs in YAML, expected services/keys present, the Swarm stack is provably stateless, k3s manifests carry a not-for-prod marker; a real docker compose config validation runs only when a Docker daemon is actually reachable.
  • Bug found and fixed while writing tests: Install-K3sServer.ps1 line 88 had a double-wrapped $((if(...){...}else{...})) subexpression that threw The term 'if' is not recognized... on every invocation (including -WhatIf) — this had shipped in Chapter 1 without being caught, because nothing had actually run the script before. Fixed to a single $(...). This is exactly the class of bug hermetic -WhatIf execution tests (as opposed to parse-only checks) exist to catch.
  • Documentation gap found and fixed: kubernetes/README.md promised every k3s script carries a # REQUIRES REAL HARDWARE banner; Get-K3sKubeconfig.ps1 and Teardown-K3s.ps1 didn't. Added.
  • CI (.github/workflows/ci.yml): test (Pester + coverage floor), churn (suite run 5x, fail on any disagreement), security (Semgrep via Docker). Runs on [self-hosted, home-ci, windows] — see the workflow's top comment for the interim-label note.
  • Measured local coverage on the scripts CI can instrument: 34.3% against a documented floor of 25% (see TESTING.md for why the house 70% floor doesn't fit this repo's shape).