cad-atlas/.context/PROJECT.md

cad-atlas

Identity

• Name: cad-atlas
• Owner: Mathias
• Client: personal
• Repo: git.d-ma.be/mathias/cad-atlas
• Status: active
• Stack: Go + Templ + HTMX + CDN Tailwind (template-go-web). Cross-project conventions: ~/dev/.context/AGENT.md.

What this is

A visual atlas of the Continuous Agentic Development (CAD) workflow — the full path from a captured signal to a deployed k3s pod, one screen, reel-style ("From Signal to Pod"). It exists to (a) make the homelab's agentic delivery pipeline legible to a human, and (b) render the CAD audit chain — which doubles as the regulated-industry audit artifact.

Core thesis: the CAD audit chain is the visualization data. TELOS → goal → spec → issue → execution → attestation → deploy is both the trace and the audit package. Phase C renders it once and serves two masters (observability + compliance).

Phases

• Phase A — static hero viz (current). Self-contained internal/web/static/cad-atlas.html, data-driven from a hand-authored STAGES array (ground-truth snapshot from brain, 2026-07-19). Served at / by internal/web/handler.go via go:embed. Reel-parity: SVG spine with arrowheads, animated pulse, dashed feedback bus (stage 08 → TELOS), replay + slow-mo.
• Phase B — generated-from-source. Parse brain docs + .gitea/workflows + infra manifests → render the graph so it can't drift from config.
• Phase C — live trace viewer. Replace the static STAGES array with live reads of the assessor-loop attestation ledger + brain session_log + Gitea run API + Flux events. This is the prize: a real signal→pod trace viewer that is also the audit package.

The workflow it visualizes (9 stages)

00 Signals (Applied AI Radar → mathias/signals) → 01 TELOS (intention substrate) → 02 Strategic session (claude.ai frontier + LLM Council + Autoresearch Council) → 03 Spec → Gitea issue (agent-ready contract; Ed25519 admission #36; var-go Oath) → 04 Human dispatch gate (the only checkpoint; session-dispatch bridge → cad-dispatch.yml) → 05 Execute · agentsquad (serve/taskqueue, exec+review loop, risk LOW/MED/HIGH, dma-cli routing, assessor-loop ledger) → 06 PR → CI (go test/vet/lint/govulncheck + var-go/oath gate) → 07 CD → pod (Flux GitOps → k3s on koala) → 08 Loop back (outcome scored vs TELOS goal).

Three orthogonal governance gates

Gate	Guards	Where
Ed25519 admission controller (#36)	spec integrity (issue untampered)	stage 03
dispatch-allow (.dispatch-allow + mathias/dispatch allowlist)	repo eligibility (may agents run here)	stage 04/05
var-go Oath (cmd/vargo-gate, commit status var-go/oath)	output correctness (PR satisfies the Oath; floor over reviewer, anti-rubber-stamp #55)	stage 06

Dogfooding

This repo is built through the workflow it depicts. It is dispatch-allow-enabled, and its own build increments are governed by a var-go Oath embedded in their spec issues (see the Stage-03 tracking issue). Bootstrapping honesty (per swedsl honest-stub discipline): cmd/vargo-gate is wired into .gitea/workflows/cd.yml's oath job (issue #1) — it runs on every pull_request, fetches the linked issue's oath, and posts a var-go/oath commit status. But its candidate is still a hardcoded toy self-test registry, not a real PR-diff checker (swedsl's Executor question, swedsl#27, is unbuilt) — it fails closed against any real oath. The status is not required by branch protection, so it can't block merges yet; enabling that waits on the real-diff Executor. Disclosed in the CI config comment, this doc, and docs/INCEPTION-OATH.md.

Brain references (source of truth — brain_get <path>)

• wiki/homelab/decisions/cad-atlas-audit-chain-is-viz-data.md — this project's genesis note: the audit-chain-is-viz-data thesis, the three gates, template-go-web footguns
• wiki/homelab/decisions/inception-sprint-and-oath.md — the Inception Sprint + Oath methodology (this repo's birth is the worked example); see docs/INCEPTION-OATH.md for the kept Oath
• knowledge/workflow-idea-to-running-service.md — Double Diamond idea→service workflow
• wiki/homelab/decisions/continuous-agentic-development-cad-concept-2026-06-16.md — CAD definition
• wiki/agentsquad/decisions/cad-dispatch-bridge.md — claude.ai → agentsquad trigger path
• wiki/agentsquad/facts/llm-council-design-and-first-runs-2026-06-21.md — LLM Council
• wiki/agentsquad/decisions/autoresearch-council-sibling-pipe.md — Autoresearch Council
• wiki/agentsquad/decisions/serve-http-task-api.md — agentsquad serve/taskqueue
• knowledge/var-go-anchor-to-span-spike-verdict.md — var-go runner + CAD gate seam
• knowledge/swedsl-vargo-sprint1-enforcement-teeth-verdict.md — vargo-gate enforcement teeth
• wiki/assessor-loop/decisions/assessor-loop-genesis.md — attestation ledger (Phase C source)
• wiki/homelab/facts/homelab-network-topology-reference.md — koala/iguana/flamingo/piguard

External references

• Inspiration reel — "From Inbox to Shipped" pipeline viz: https://www.instagram.com/reel/DY92L7bu27j/
• karpathy/llm-council — origin of the Council pattern
• Double Diamond design process (Discover/Define/Develop/Deliver)

Run

task check      # lint + vet + test (CI gate)
task run        # build + serve at http://localhost:8080  → the atlas

Deploy note

CD (.gitea/workflows/cd.yml) deploys to k3s namespace cad-atlas via Flux. Per the known template-go-agent CD gap: the deploy job stays RED until mathias/infra has k3s/apps/cad-atlas/deployment.yaml. check + build are the real bootstrap gate.