docs(agents): correct the Validation topology in go-template AGENTS.md

.github/workflows/validate-scaffold.yaml

@@ -6,8 +6,7 @@ on:
 
 permissions: {}
 
-# Template-repo-only scaffold-integrity gate for three non-Go surfaces that
-# the shared Go gate does not cover:
+# Template-repo-only scaffold-integrity gate for three non-Go surfaces:
 #   * scripts/rename-placeholders.sh — the first thing a newcomer runs after
 #     `Use this template`; a silent regression ships broken to every generated
 #     project.
@@ -17,8 +16,9 @@ permissions: {}
 #     copied guidance would create a second source that silently drifts.
 # This job runs ONLY in the template repo; it no-ops in projects created from it
 # (the guard below is false there), mirroring how cd.yaml/release.yaml run only
-# downstream. Generated projects delete the onboarding script and validate their
-# own code via the injected validate-go-project workflow.
+# downstream. Generated projects delete the onboarding script and gate their own
+# code through whatever Go workflow their organisation injects (see AGENTS.md
+# *Validation*) — this repo has no such injection.
 jobs:
   validate-scaffold:
     name: Validate Scaffold

AGENTS.md

@@ -43,18 +43,36 @@ golangci-lint run        # run the configured linters
 
 Workflow YAML changes should pass `actionlint`.
 
-These local checks are for fast feedback — **CI does verify the scaffold.** A
-**repository ruleset** ("Require workflows to pass before merging for Go")
-injects the shared `devantler-tech/reusable-workflows` **`validate-go-project`**
-workflow on every PR and the merge queue; it runs `go build`, `go test`,
-`golangci-lint`, dead-code analysis, MegaLinter, and Code-Quality coverage
-(change-detection skips the Go jobs on non-Go PRs). The repo's own `ci.yaml` is
-a separate, trivially-passing `CI - Required Checks` aggregator — **not** the Go
-gate — so do **not** wire `validate-go-project` into `ci.yaml`; that would
-double-run every job (see go-template#76, closed as invalid).
-
-The scaffold's **non-Go integrity checks** sit outside that Go gate, so they
-have their own template-repo-only workflow, `validate-scaffold.yaml`. It runs
+These local checks are for **fast feedback** and are the primary Go
+verification for the template repository itself: CI here has **no dedicated Go
+build/test/lint gate**. It is not absent, though — the `Validate Scaffold` job
+(below) renames the scaffold into a throwaway copy and runs `go build ./...` and
+`go test ./...` against it (`scripts/rename-placeholders.test.sh`), so a scaffold
+that stops building or testing fails a PR; there is just no dedicated
+`golangci-lint` / dead-code / MegaLinter / coverage gate on this repo. A **PR**
+is gated by `Validate Scaffold`, `CI - Required Checks` (a trivial aggregator in
+the repo's own `ci.yaml`), and the org-required workflows — CodeQL (`Analyze
+(go)` / `Analyze (actions)`), Scan for Workflow Vulnerabilities (`zizmor`),
+Dependency Review, and Enable Auto-Merge (`eligibility`). The **merge queue**
+runs `ci.yaml` **plus** those org-required workflows — they all declare
+`merge_group` and complete via no-op eligibility paths, so they appear in the
+merge-group check set too. Only `validate-scaffold.yaml` is
+`pull_request`-only, so `Validate Scaffold` does **not** run on a merge-group
+SHA. Required status checks come from the org "Require status checks to pass"
+ruleset (context: `CI - Required Checks`); there is **no** "…for Go" workflow
+ruleset and **no** `validate-go-project` / `reusable-workflows` injection on this
+repo (that repo was archived into `devantler-tech/actions`). Keep `ci.yaml` the
+trivial aggregator it is — do **not** add heavy Go build/test/lint jobs to it
+(see go-template#76, closed as invalid).
+
+**Generated** projects gate Go build/test differently — **not** via the
+scaffolded `ci.yaml`, which is the same empty aggregator. **devantler-tech**
+instances get build/test from org-injected ruleset workflows; instances
+**outside** devantler-tech inherit no real build/test workflow and must replace
+`ci.yaml` with their own (see the README and `.templatesyncignore`).
+
+The scaffold's **non-Go integrity checks** are the template-repo-specific gate,
+run by their own template-repo-only workflow, `validate-scaffold.yaml`. It runs
 `sh scripts/validate-agent-shims.test.sh`,
 `sh scripts/rename-placeholders.test.sh`, and
 `sh .github/scripts/run-mockery.test.sh`. Run the matching check locally when
@@ -114,7 +132,7 @@ plus an `--experimental` opt-in (or a config gate), and only add the SDK where
 richer evaluation is genuinely needed. Same default-off, remove-after-rollout
 lifecycle either way.
 
-**Validate before any PR (locally):** `golangci-lint fmt` (if configured), `go build ./... && go test ./...`, `golangci-lint run` — local checks for fast feedback (the ruleset-injected `validate-go-project` workflow re-runs build/test/lint/coverage on the PR — see *Validation* above; don't duplicate it into `ci.yaml`). Workflows → `actionlint`.
+**Validate before any PR (locally):** `golangci-lint fmt` (if configured), `go build ./... && go test ./...`, `golangci-lint run` — local checks for fast feedback; the template has no dedicated Go lint gate in CI (its only CI build/test is the `Validate Scaffold` job's smoke of a renamed scaffold copy — see *Validation* above), so don't add heavy Go jobs to `ci.yaml`. Workflows → `actionlint`.
 
 **Task menu** (light; ≤1 high-value item per run):
 

README.md

@@ -10,9 +10,9 @@ A minimal, batteries-included Go template for new projects. Skip the boilerplate
 
 - **Idiomatic scaffold** — a no-op `main.go` plus the conventional `cmd/`, `internal/`, and `pkg/` layout, ready for your first package. A minimal [`pkg/example`](pkg/example) package with a table-driven test shows the house testing pattern — replace it with your own.
 - **Feature-flag-first** — [`pkg/featureflag`](pkg/featureflag) wires the portable [OpenFeature](https://openfeature.dev/) Go SDK so a **service** can land every new feature behind a flag, default-off, and flip it on only after validation (swap the in-memory provider for [flagd](https://flagd.dev/) or a managed backend). A **CLI** can stay dependency-free instead — gate experimental commands behind cobra `Hidden` + an `--experimental` opt-in, reaching for the SDK only when you need richer evaluation. Delete it when you add your own.
-- **Linting & formatting** — [`golangci-lint`](https://golangci-lint.run/) v2 (formatters + `default: all` linters) in CI, with [MegaLinter](https://megalinter.io/) covering everything else. A [pre-commit](https://pre-commit.com/) hook runs `golangci-lint` formatting (and `mockery` mock generation) locally on commit.
+- **Linting & formatting** — ready-to-use [`golangci-lint`](https://golangci-lint.run/) v2 (formatters + `default: all` linters) and [MegaLinter](https://megalinter.io/) configs. A [pre-commit](https://pre-commit.com/) hook runs `golangci-lint` formatting (and `mockery` mock generation) locally on commit; in CI they run wherever your organisation injects a Go workflow (see [*Validation*](AGENTS.md#validation)).
 - **CI/CD** — a required-checks workflow on pull requests and the merge queue, plus a [GoReleaser](https://goreleaser.com/) release pipeline (`cd.yaml`) triggered on `v*` tags.
-- **Coverage** — `go test` coverage reported via [GitHub Code Quality](https://docs.github.com/code-security/code-quality).
+- **Coverage** — a `go test` coverage config ready to report via [GitHub Code Quality](https://docs.github.com/code-security/code-quality) once your CI runs it.
 - **Dependency management** — [Dependabot](https://docs.github.com/code-security/dependabot) keeps Go modules and pinned GitHub Actions current (daily).
 - **Agent-ready** — [`AGENTS.md`](AGENTS.md) conventions and a `.claude/skills/maintain` card so the autonomous Daily AI Assistant (and any agentic tool) can maintain the repo.