# 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): the Oath is
**defined** but `cmd/vargo-gate` is **not yet wired** into this repo's CI — until it is, the Oath
is advisory here. Wiring it is a first tracked task; disclosed in code, this doc, and CI config.

## 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`](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

```bash
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.