ADR-0020: Second-wave praetor conformance and release hardening¶
- Status: Proposed
- Date: 2026-09-15
- Deciders: @lusoris
- Tags: governance, ci, security, releases, praetor
Context¶
ADR-0019 adopted
cordanaLLM/praetor governance in full but left several gaps open: praetor's
own gate (internal/gating/pipeline.go) refused to run at all because
.golangci.yml and .gosec.json lived under tools/ instead of the repo
root; the checked-in .devcontainer/ referenced a docker/dev/Dockerfile
that did not exist; .workingdir/ was tracked in git with a .gitignore
comment declaring that intentional, which conflicts with praetor's HISS-17
("State Ledger Discipline": the directory must be private and git-ignored
fleet-wide); praetor's own lefthook scaffold duplicated golusoris-specific
hook logic; the branch protection enforced on GitHub was hand-maintained
classic protection rather than a declared policy; and the release pipeline
had no immutability or source-tree SBOM guarantees to match the
supply_chain block (slsa_level: 3, enforce_cosign, require_sbom)
already declared in .standards.yaml. Downstream apps also consumed the
framework's reusable workflows (ci-go.yml, release-go.yml,
scorecard.yml) through the template/ scaffold, which had drifted onto a
broken pin. This ADR records the conformance and release-hardening work
that closed those gaps on 2026-09-14 and 2026-09-15, tracked under epic
issue #429 and its per-area tasks #432–#434.
Decision¶
.workingdir/becomes private (HISS-17). The directory (12 tracked files: routing ledger,OPEN.md/STATE.md/QUESTIONS.md, archive) is untracked and.gitignoregains praetor's exact/.workingdir/rule plus a nested.workingdir/rule for per-package copies (#495). This reverses a convention that had been declared only in a.gitignorecomment, not in any Accepted ADR — no ADR is superseded by this change. Session state that previously lived in tracked.workingdir/files now persists outside the repository.- Praetor's lefthook jobs are merged in, not swapped in wholesale
(HISS-19).
context-check,hiss-audit, theagent-checkpoint-*jobs, post-commitstate-sync/dedupe-cadence, and the pre-pushsecurity/audit/gatejobs are adopted verbatim fromstandardsctl adopt --lock-source-root=<praetor>. golusoris-specific scripts that cover the same ground at least as strictly are kept instead of praetor's generic equivalents:scripts/hooks/gofumpt.sh(a verified strict superset of praetor's plaingofmt -w) andscripts/hooks/govet.sh(iterates everygo.modin the multi-module tree; a barego vet ./...does not). Two pre-push jobs,flavor-auditandgate, are wired intolefthook.ymlbut held back (commented out of the activecommands:block) because praetor misclassifies this library'sgo.mod+cmd/layout as thego-serviceflavor and demands artifacts a library does not need (cordanaLLM/praetor#36);standardsctl gate run --path=.already passes stages 1–3 (lockfile, HISS scan, security) and fails only stage 4, the flavor check the held-back jobs would run (#495). #633 later removed the two held-back jobs fromlefthook.yml;.standards.yamlnow declines theworking-dir-and-flavoradoption step instead, citing the same upstream bug. - Canonical config paths.
.golangci.ymland.gosec.jsonmove to the repository root, the paths praetor's flavor definitions and gate require (#494). The priortools/gosec.exclude-rulespath-scoped exclusion list is replaced by inline// #nosec Gxxx -- reasoncomments at each finding, which — unlike the exclusion file — are recognized by bothgosecand golangci-lint's embedded gosec linter from the same annotation. - The devcontainer is regenerated from praetor's source bundle. The
previous
devcontainer.jsonbuilt from aDockerfilethat was never committed, so the container had been broken since it was added.standardsctl devcontainer --source-root=<praetor> --force(praetorccfe6f0) replaces it withDockerfile.praetorand a three-part base64 source bundle that buildspraetorctlinside the container (#493). - A branch ruleset is declared with
single_maintainerreview mode..standards.yamlsetsbranch_protection.review_mode: single_maintainer; praetor renders this to zero required approving reviews and no code-owner review, matching praetor's own dogfooded policy for a solo maintainer.praetorctl syncregenerates.github/rulesets/main.jsonfrom that policy and the workflow tree; currentfae37a35d44erenders 24 exact unconditional contexts, including matrix legs. It cannot renderCI success(if: always()) or the conditional pull-request gates for PR title, DCO, and dependency review becauseRequiredStatusContextsexcludes those job conditions (cordanaLLM/praetor#76). Measured state on 2026-10-19: cordanaLLM/praetor#76 is closed, and the activepraetor-main-protectionruleset onmainmatches.github/rulesets/main.jsonexactly (same rule types, 45 required contexts includingCI success, zero required approvals, signed commits, linear history). Classic branch protection still runs alongside it and requiresCI successandPR title (Conventional Commits). - Releases are immutable, with a source-tree SBOM attestation workflow. GitHub
immutable releases are enabled for this repository (
v0.10.1is the first release published under it). Because an immutable release accepts no assets after publication,sbom.ymlgenerates SPDX and CycloneDX SBOMs for the tagged source tree and attempts to publish them as GitHub attestations (actions/attest, Sigstore keyless) and workflow artifacts, rather than as release-asset uploads (#508). This is in addition to the per-archive SPDX SBOMsrelease.ymlalready emits through goreleaser and signs with cosign keyless signatures andactions/attest-build-provenance. Hosted publication remains an observed result, not a configuration guarantee: the v0.12.0 release and per-archive SBOMs succeeded, while its separate source-tree workflow failed during Rekor publication. Later tags proved the retry path:sbom.ymlsucceeded for every tag fromv0.16.1throughv0.17.0(v0.17.0 run). template/pins the reusable workflows at a tagged commit, not a floating ref.template/.github/workflows/{ci,release}.ymlreferencegolusoris/golusoris/.github/workflows/{ci-go,release-go,scorecard}.ymlby full commit SHA with a trailing# vX.Y.Zcomment (380b26797a8552c8b8aba03d53209b8997f2b1be # v0.10.1), corrected onto the current tagged release after an earlier automated dependency bump had landed the template on a broken pin (#500).- Withdrawn: admin merges while the ARC fleet was constrained. This
decision covered the period when the self-hosted
arc-cauda-golusoris-golusorisrunner set could not keep up with the required checks. ADR-0021 moved CI to GitHub-hosted runners, so required checks no longer wait on that fleet and no admin-merge exception remains.
Alternatives considered¶
| Option | Pros | Cons | Why not chosen |
|---|---|---|---|
Keep .workingdir/ tracked, ask praetor to special-case golusoris |
No git-history churn; state stays inspectable in-tree | HISS-17 is a fleet-wide invariant enforced by praetor's own Git metadata gate; a per-repo exception defeats "one behavior, one implementation" | Fleet-wide conformance (HISS-19) over a local carve-out |
Replace lefthook.yml wholesale with praetor's generated scaffold |
Zero merge work, always in sync with praetor | Drops golusoris's stricter multi-module govet.sh and gofumpt-over-gofmt reasoning; silently loses coverage in the multi-module repository |
Verified check-by-check merge, kept where golusoris's script covers strictly more |
| Suppress the flavor mismatch (patch praetor's flavor detector locally, or fake the manifest) | flavor-audit/gate could stay enabled today |
Masks a real upstream bug (praetor#36) instead of fixing it; a local patch on a fleet-wide tool re-diverges the fleet | Held back with an explicit re-enable condition tied to the upstream fix |
Leave .golangci.yml/.gosec.json under tools/ and symlink from root |
Avoids repointing every consumer | Praetor's flavor definitions look for the file at the root path, not a symlink target, by name; standardsctl gate run failed before reaching the security scan |
Canonical root paths, every consumer repointed |
| Mutable releases, SBOMs attached as release assets | One artifact surface (the release page) | Immutable releases (once enabled) reject post-publication asset uploads outright | GitHub attestations for source-tree SBOMs instead of release assets |
| Apply the new ruleset to GitHub immediately | Enforcement matches the declared policy right away | Rulesets carry no admin bypass; an in-flight fleet-gated PR that cannot yet satisfy every declared check would be locked out with no override | Declare the policy now, apply it once in-flight PRs land |
| Block every merge on ARC-backed required checks finishing, regardless of queue depth | Uniform enforcement, no manual step | The fleet is measurably undersized today; a solo maintainer with a green local gate would otherwise be blocked by runner contention alone | Documented, commented admin-merge exception until the fleet is resized; withdrawn by ADR-0021 |
Consequences¶
- Positive: the HISS baseline remains zero. Praetor
fae37a35d44ereported two false-positive HISS-07 findings for the canonicalpanic(http.ErrAbortHandler)connection-abort path; both upstream issues are now closed: cordanaLLM/praetor#331 (the scanner fix) and cordanaLLM/praetor#393 (the signed-waiver verifier). No baseline or gate bypass masks a finding.standardsctl gate runpasses stages 1–3; the devcontainer builds andstandardsctl devcontainer --verifypasses; the branch protection policy is declared in a file (.github/rulesets/main.json) instead of only existing as a GitHub UI setting; releases carry build provenance attestations, cosign signatures, and per-archive SBOMs, while a separate workflow publishes source-tree SBOM attestations; downstream apps pin reproducible, verifiable workflow versions instead of a floating branch ref. - Negative: flavor conformance (stage 4 of praetor's gate) is not
enforced pending an external fix:
cordanaLLM/praetor#36
is still open, and on 2026-10-19 the pinned engine still audits this
library as
go-service(praetorctl flavor audit .exits 1 at 62.5%, missing a serviceDockerfileandsecurity.yml);.workingdir/state is no longer versioned in git, so continuity across sessions depends entirely on tooling outside the repository; the generated ruleset does not carry the conditionalPR title (Conventional Commits)check, which only classic branch protection still requires. - Neutral / follow-ups: remote ruleset reconciliation is done; the
remaining step under epic task #434 is retiring classic branch protection
once the ruleset carries every check it requires. Adopt the flavor step
once cordanaLLM/praetor#36 is fixed and
praetorctl flavor audit .exits 0 onmain. The admin-merge exception needs no follow-up: ADR-0021 withdrew it.
References¶
- ADR-0017 · ADR-0019
- PRs: #484 (drop retired CodeQL job, restore Scorecard), #487 (
runs-on/working-directoryinputs forci-go.yml), #488 (praetor agent harness), #492 (skip container-backed testutil helpers under-short), #493 (devcontainer regeneration, HISS-01 recursion), #494 (canonical.golangci.yml/.gosec.jsonpaths, inline#nosec), #495 (praetor lefthook adoption,.workingdir/untracked), #496 (release v0.10.0), #498 (ci-go.ymlmodule-matrix fix), #499 (release v0.10.1), #500 (template pin corrected to v0.10.1), #503 (HISS baseline burned down to 0), #506 (release v0.10.2), #508 (source-tree SBOM attestations), #509 (branch ruleset declaration) - Upstream: cordanaLLM/praetor#36 (flavor misdetection for a
go.mod+cmd/library) - Epic: #429; tasks #432, #433, #434
- HISS-17/HISS-18/HISS-19 specifications: https://github.com/cordanaLLM/praetor/blob/main/docs/wiki/HISS-Matrix.md