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>
63 lines
3.9 KiB
Markdown
63 lines
3.9 KiB
Markdown
# cad-atlas — Inception Sprint Oath
|
||
|
||
The acceptance contract for standing up cad-atlas. The sprint is finalized only when this
|
||
Oath holds. Methodology: brain `wiki/homelab/decisions/inception-sprint-and-oath.md`.
|
||
|
||
> **Status of enforcement:** this Oath is currently **advisory** (human-verified). `var-go/oath`
|
||
> gates a real candidate now (`oathcandidate/`, #8 — parses the committed CI workflow, TDD'd
|
||
> pass/fail-closed) but isn't yet required by branch protection pending a real-PR confirmation.
|
||
> See the honesty rule below.
|
||
|
||
## General clauses (any inception sprint)
|
||
|
||
| # | Clause | Status | Evidence |
|
||
|---|--------|--------|----------|
|
||
| G1 | Repo born from template on Gitea, dispatch-eligible | ✅ | `create_project_from_template`, `.dispatch-allow`, dispatch-allowlisted |
|
||
| G2 | Self-contained context + brain deep-links + external refs | ✅ | `.context/PROJECT.md`, `README.md` |
|
||
| G3 | Green CI on main: build · vet · lint · test (TDD) | ✅ | Genuinely green from run 19 (commit 68adfe7). NOTE: runs 16–18 were *hollow* — a template guard bug (template-go-web#9) skipped every job; fixed here. `internal/web/handler_test.go` |
|
||
| G4 | Genesis learning persisted to brain, linked from repo | ✅ | `wiki/homelab/decisions/cad-atlas-audit-chain-is-viz-data.md` |
|
||
| G5 | Discovered findings filed as tracker issues | ✅ | template-go-web#8, local-dev#20 |
|
||
| G6 | SemVer tag marks the milestone (closing act) | ✅ | `v0.1.0` |
|
||
| G7 | Agent-ready spec issue for the next increment | ✅ | #1 |
|
||
|
||
## Specific clauses (cad-atlas)
|
||
|
||
| # | Clause | Status | Evidence |
|
||
|---|--------|--------|----------|
|
||
| S1 | Atlas served at `/`, renders all 9 stages signal→pod | ✅ | `internal/web/handler.go` + `static/cad-atlas.html` |
|
||
| S2 | Oath covered in the viz (stages 03 + 06) | ✅ | var-go Oath nodes in the atlas |
|
||
| S3 | `var-go/oath` enforces cad-atlas's own PRs | ⏸ **real candidate wired, not enforcing → #8** | `oathcandidate/` gates the real `.gitea/workflows/cd.yml` (TDD green: passes real file, fails closed on a fixture missing the job) via swedsl's sandboxed `SubprocessGate` (swedsl#35/#38). Not yet branch-protection-required — awaiting confirmation on a real PR. See honesty rule. |
|
||
|
||
## Deployment
|
||
|
||
Live at **https://atlas.d-ma.be** (Authentik forward-auth — authed users only) on koala k3s:
|
||
namespace `cad-atlas`, 1 replica, `cad-atlas:80 → :8080` (manifests in `mathias/infra`
|
||
`k3s/apps/cad-atlas/`, reconciled by Flux). CI `deploy` job **auto-deploys** on every main push —
|
||
`INFRA_DEPLOY_KEY` (write deploy-key `cad-atlas-ci` on infra) is wired (#2 done).
|
||
|
||
## The honesty rule
|
||
|
||
A clause blocked by an external dependency is **descoped and tracked, never marked satisfied** —
|
||
a self-lying Oath is a rubber stamp, the exact failure the Oath exists to prevent. S3's real
|
||
candidate is wired (#8) but branch-protection enforcement waits on a real-PR confirmation, tracked
|
||
there, not claimed here. The `DMABE_GITEA_API_TOKEN` Actions secret is pre-provisioned so #1 and
|
||
#8 both landed without a secret-write.
|
||
|
||
Also surfaced by #8: this file's own "Oath (advisory form)" below predates the discovery that
|
||
var-go's parser requires single-line, period-separated sentences with no `Given`/`Then`/`And`
|
||
keyword stripping — it has never been machine-gated and would need reformatting first if it ever is.
|
||
|
||
## The Oath (advisory form)
|
||
|
||
```var
|
||
Given a new software thing is being stood up as an inception sprint
|
||
Then its repo is born from template on Gitea and is dispatch-eligible
|
||
And its context is self-contained with brain deep-links and external references
|
||
And CI on main is green across build, vet, lint and test
|
||
And the genesis learning is persisted to brain and linked from the repo
|
||
And every discovered finding is filed as a tracker issue
|
||
And an agent-ready spec issue exists for the next increment
|
||
And a SemVer tag marks the milestone as the closing act
|
||
And any clause blocked by an external dependency is descoped and tracked, never claimed
|
||
```
|