generated from mathias/template-go-web
mathiasandClaude Sonnet 5
805b76d7c3
oathcandidate/ is a separate Go module (mirrors swedsl's own oath/testdata/selfcandidate pattern, keeping var-go's transitive deps out of the deployed atlas binary) whose Build() parses the committed .gitea/workflows/cd.yml and checks the "oath" job exists and invokes cmd/vargo-gate. TDD: passes against the real file, fails closed on a fixture missing the job. Rewires the oath CI job to go-run vargo-gate from its real module path (git.d-ma.be/mathias/swedsl/oath/cmd/vargo-gate@oath/v0.28.0, unblocked by swedsl#35/#38) against VARGO_CANDIDATE_DIR=oathcandidate, instead of checking out swedsl and gating its hardcoded toy fixture. Private-module auth via a short-lived GIT_ASKPASS script (token never in argv, never written to git config, matches act_runner's env:-block-with-secrets gotcha). Discovered along the way: var-go's parser needs single-line, period-separated oath sentences with no Given/When/Then/And keyword stripping — this repo's older oaths (incl. #1) used an unverified multi-line keyword-prefixed style. #8's oath uses the proven format. Still not required by branch protection pending a real-PR confirmation. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
99 lines
5.8 KiB
Markdown
99 lines
5.8 KiB
Markdown
# 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). `cmd/vargo-gate` is wired into `.gitea/workflows/cd.yml`'s `oath` job —
|
|
on every pull_request it fetches the linked issue's oath and gates cad-atlas's **own real
|
|
candidate** (`oathcandidate/`, #8): it parses the committed `.gitea/workflows/cd.yml` and checks
|
|
the `oath` job actually exists and invokes `cmd/vargo-gate`, then posts the `var-go/oath` commit
|
|
status. This is a real check (TDD'd: passes on the real file, fails closed on a fixture missing
|
|
the job), not swedsl's toy self-test stub — swedsl#35 (import path) and swedsl#38 (real-candidate
|
|
subprocess gating) unblocked it. Still **not** required by branch protection until proven green on
|
|
a real PR (#8). 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`](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.
|