feat(oath): gate cad-atlas's own real candidate, not swedsl's toy stub (#8)

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>

oathcandidate/build.go

@@ -0,0 +1,108 @@
+// Package oathcandidate supplies cad-atlas's own real var-go candidate (cad-atlas#8):
+// steps that gate its own CI-workflow oath by actually parsing the committed
+// .gitea/workflows/cd.yml, not a stub that hardcodes an unrelated toy vocabulary.
+// var-go injects and owns the gate across the subprocess boundary (SubprocessGate,
+// ADR-0003), so this package supplies only the prose->behaviour binding and never a
+// verdict — it cannot self-certify.
+package oathcandidate
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+
+	oath "git.d-ma.be/mathias/swedsl/oath"
+	"gopkg.in/yaml.v3"
+)
+
+// workflowState is the candidate's domain: the job names and concatenated step-run
+// scripts parsed out of one Gitea Actions workflow file.
+type workflowState struct {
+	jobNames map[string]bool
+	jobRuns  map[string]string // job name -> every step's `run:` script, concatenated
+}
+
+type workflowFile struct {
+	Jobs map[string]struct {
+		Steps []struct {
+			Run string `yaml:"run"`
+		} `yaml:"steps"`
+	} `yaml:"jobs"`
+}
+
+// Build returns cad-atlas's candidate registry. cmd/vargo-gate runs the generated
+// harness with cwd = this module's own directory (SubprocessGate's
+// cmd.Dir = candidateModuleDir contract) — one level under the cad-atlas repo root
+// in cad-atlas's real layout — so a workflow path in the oath text like
+// ".gitea/workflows/cd.yml" is read relative to "..".
+func Build() *oath.Registry[workflowState] {
+	reg := oath.NewRegistry[workflowState]()
+
+	if err := reg.Stimulus(`the CI workflow file {string} is parsed`,
+		func(_ workflowState, path string) workflowState {
+			return parseWorkflow(path)
+		}); err != nil {
+		panic(err)
+	}
+
+	if err := reg.Sensor(`it defines a job named {string}`,
+		func(s workflowState, name string) string {
+			if s.jobNames[name] {
+				return name
+			}
+			return "<no such job>"
+		}); err != nil {
+		panic(err)
+	}
+
+	// Checks what the workflow file can actually attest to: the job's run script
+	// invokes the gate binary. The "var-go/oath" commit-status context string
+	// itself lives in vargo-gate's Go code, not the YAML — not something this
+	// file-level check can see, so it isn't what's asserted here.
+	if err := reg.Sensor(`the job named {string} invokes {string}`,
+		func(s workflowState, job, cmd string) (string, string) {
+			run, ok := s.jobRuns[job]
+			foundJob := "<no such job>"
+			if ok {
+				foundJob = job
+			}
+			foundCmd := cmd
+			if !ok || !strings.Contains(run, cmd) {
+				foundCmd = "<not invoked>"
+			}
+			return foundJob, foundCmd
+		}); err != nil {
+		panic(err)
+	}
+
+	return reg
+}
+
+// parseWorkflow reads and parses a Gitea Actions workflow file relative to the
+// repo root (see Build's doc comment for the cwd contract). A read or parse
+// failure returns an empty state — every sensor then observes "not found",
+// which fails the gate closed rather than silently skipping the check.
+func parseWorkflow(repoRelativePath string) workflowState {
+	state := workflowState{jobNames: map[string]bool{}, jobRuns: map[string]string{}}
+
+	data, err := os.ReadFile(filepath.Join("..", repoRelativePath))
+	if err != nil {
+		return state
+	}
+
+	var wf workflowFile
+	if err := yaml.Unmarshal(data, &wf); err != nil {
+		return state
+	}
+
+	for name, job := range wf.Jobs {
+		state.jobNames[name] = true
+		var runs strings.Builder
+		for _, step := range job.Steps {
+			runs.WriteString(step.Run)
+			runs.WriteString("\n")
+		}
+		state.jobRuns[name] = runs.String()
+	}
+	return state
+}

oathcandidate/build_test.go

@@ -0,0 +1,79 @@
+package oathcandidate
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	oath "git.d-ma.be/mathias/swedsl/oath"
+)
+
+// realOath is cad-atlas#8's actual oath text — the same var block committed to
+// that issue. Gating it against the REAL checked-out .gitea/workflows/cd.yml
+// proves the candidate reads real CI config, not a fixture standing in for it.
+//
+// Format note (discovered writing this test): var-go's parser requires a
+// SINGLE-LINE paragraph — sentences are split by "." within that line, not by
+// newline — and does NOT strip Given/When/Then/And keywords before matching a
+// step. cad-atlas's older oaths (e.g. issue #1) use a multi-line, keyword-prefixed
+// style that was never actually exercised against this parser (every prior gate
+// run errored before reaching real sentence matching). Plain declarative
+// sentences, period-separated, one line — see swedsl's own gate_test.go fixtures.
+const realOath = "```var\n" +
+	`the CI workflow file ".gitea/workflows/cd.yml" is parsed. it defines a job named "oath". the job named "oath" invokes "cmd/vargo-gate".` +
+	"\n```\n"
+
+// TestBuild_GatesRealWorkflow is named before Build existed (TDD): it fails to
+// compile until Build() and the workflow-parsing steps exist, and fails to pass
+// until they parse the REAL committed cd.yml correctly — this is the file that
+// must go from red to green, not a mock.
+func TestBuild_GatesRealWorkflow(t *testing.T) {
+	// go test's cwd is already this package's dir (oathcandidate/), matching
+	// SubprocessGate's cmd.Dir = candidateModuleDir contract exactly — no chdir
+	// needed to reproduce it here.
+	verdict, err := oath.Gate([]byte(realOath), Build())
+	if err != nil {
+		t.Fatalf("Gate returned error: %v", err)
+	}
+	if !verdict.Pass {
+		if verdict.Failure != nil {
+			t.Fatalf("Gate did not pass: failure=%+v", *verdict.Failure)
+		}
+		t.Fatalf("Gate did not pass against the real committed cd.yml: %+v", verdict)
+	}
+}
+
+// TestBuild_FailsClosedOnMissingJob proves the candidate is a REAL check, not a
+// rubber stamp: gating a workflow file that has no "oath" job must fail.
+func TestBuild_FailsClosedOnMissingJob(t *testing.T) {
+	dir := t.TempDir()
+	workflowsDir := filepath.Join(dir, ".gitea", "workflows")
+	if err := os.MkdirAll(workflowsDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	noOathJob := "jobs:\n  check:\n    steps:\n      - run: go test ./...\n"
+	if err := os.WriteFile(filepath.Join(workflowsDir, "cd.yml"), []byte(noOathJob), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cwd, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	// SubprocessGate always runs the candidate with cmd.Dir = candidateModuleDir,
+	// one level under the repo root (cad-atlas's real layout) — reproduce that by
+	// chdir-ing into a sibling "candidate/" dir under the fixture root.
+	candDir := filepath.Join(dir, "candidate")
+	if err := os.MkdirAll(candDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(candDir); err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(cwd) })
+
+	verdict, err := oath.Gate([]byte(realOath), Build())
+	if err == nil && verdict.Pass {
+		t.Fatalf("expected the gate to fail closed on a workflow with no oath job, got Pass=true")
+	}
+}

oathcandidate/go.mod

@@ -0,0 +1,18 @@
+// Package oathcandidate is cad-atlas's committed real candidate: the STEPS that
+// gate its own CI-workflow oath (cad-atlas#8). Deliberately a separate module (not
+// part of the main cad-atlas module) so var-go's transitive deps (cucumber-expressions,
+// goldmark) never link into the deployed atlas binary — mirrors swedsl's own
+// oath/testdata/selfcandidate pattern.
+module oathcandidate
+
+go 1.26.4
+
+require (
+	git.d-ma.be/mathias/swedsl/oath v0.28.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	github.com/cucumber/cucumber-expressions/go/v18 v18.1.0 // indirect
+	github.com/yuin/goldmark v1.8.2 // indirect
+)

oathcandidate/go.sum

@@ -0,0 +1,16 @@
+git.d-ma.be/mathias/swedsl/oath v0.28.0 h1:q4WXlGtMlDymhmuw9Pdc025OTLs1wl8THsrz/raeMxs=
+git.d-ma.be/mathias/swedsl/oath v0.28.0/go.mod h1:kEOX7Wubf3g/HTKzuoHD4fm6zNSl55cSV/qgy+ezMoI=
+github.com/cucumber/cucumber-expressions/go/v18 v18.1.0 h1:zvZFnbmtQxwHq6ru5gHxpfBloLq9wmjoKbdwOzt/XNA=
+github.com/cucumber/cucumber-expressions/go/v18 v18.1.0/go.mod h1:+Qe2kvmilsdGRFJ+zlkjXp84rPEf6O/idcoOsvnIORY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/yuin/goldmark v1.8.2 h1:kEGpgqJXdgbkhcOgBxkC0X0PmoPG1ZyoZ117rDVp4zE=
+github.com/yuin/goldmark v1.8.2/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=