Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/workflows/container-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ jobs:
- uses: actions/checkout@v7
with:
repository: crunchtools/constitution
ref: ${{ inputs.constitution-ref || 'v1.45.0' }}
ref: ${{ inputs.constitution-ref || 'v1.46.0' }}
path: .constitution
persist-credentials: false
- id: r
Expand Down Expand Up @@ -340,7 +340,7 @@ jobs:
- uses: actions/checkout@v7
with:
repository: crunchtools/constitution
ref: ${{ inputs.constitution-ref || 'v1.45.0' }}
ref: ${{ inputs.constitution-ref || 'v1.46.0' }}
path: .constitution
persist-credentials: false
- if: needs.build.outputs.pushed == 'false'
Expand Down Expand Up @@ -416,7 +416,7 @@ jobs:
- uses: actions/checkout@v7
with:
repository: crunchtools/constitution
ref: ${{ inputs.constitution-ref || 'v1.45.0' }}
ref: ${{ inputs.constitution-ref || 'v1.46.0' }}
path: .constitution
persist-credentials: false
- env:
Expand Down Expand Up @@ -455,7 +455,7 @@ jobs:
- uses: actions/checkout@v7
with:
repository: crunchtools/constitution
ref: ${{ inputs.constitution-ref || 'v1.45.0' }}
ref: ${{ inputs.constitution-ref || 'v1.46.0' }}
path: .constitution
persist-credentials: false
# resolve runs only on push; a dispatch or schedule run on a v* ref
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dependency-audit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ jobs:
- uses: actions/checkout@v7
with:
repository: crunchtools/constitution
ref: v1.45.0
ref: v1.46.0
path: .constitution
persist-credentials: false
- name: Install uv
Expand Down
9 changes: 5 additions & 4 deletions .github/workflows/gatehouse.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ permissions: {} # default-deny; each job grants only what it needs

jobs:
# ── 1) Protect the workflow files themselves ────────────────────────────────
# Rejects PRs from forks that touch .github/workflows/. Safe under
# Rejects PRs from forks that touch .github/workflows/ or .sdlc/ (the
# launcher the required `sdlc ci` check runs). Safe under
# pull_request_target because it only reads the changed-file LIST via the
# API — it never checks out or runs your code. And because pull_request_target
# runs the BASE version of this file, a PR can't edit this job to disable it.
Expand Down Expand Up @@ -66,11 +67,11 @@ jobs:
echo "Head branch is in $GITHUB_REPOSITORY; allowing."; exit 0
fi
# Both sides of a rename: `gh pr diff --name-only` lists only the new
# path, so a fork could move a workflow out of .github/workflows/ unseen.
# path, so a fork could move a file out of .github/workflows/ or .sdlc/ unseen.
changed="$(gh api --paginate "repos/$GITHUB_REPOSITORY/pulls/$PR/files" \
--jq '.[] | .filename, (.previous_filename // empty)')"
if echo "$changed" | grep -qE '^\.github/workflows/'; then
echo "::error::PR modifies .github/workflows/ — not accepted from external contributors."
if echo "$changed" | grep -qE '^(\.github/workflows|\.sdlc)/'; then
echo "::error::PR modifies .github/workflows/ or .sdlc/ — not accepted from external contributors."
# Explain once, on the PR event; replies re-run the check, not the comment.
if [ "$EVENT" = "pull_request_target" ]; then
gh pr comment "$PR" --repo "$GITHUB_REPOSITORY" --body \
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/validate.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ jobs:
- uses: actions/checkout@v7
with:
repository: crunchtools/constitution
ref: v1.45.0
ref: v1.46.0
path: .constitution
persist-credentials: false
- uses: actions/setup-python@v7
Expand Down
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,23 @@ Entries through 1.14.0 are derived from the Ratification History table in

## [Unreleased]

## [1.46.0] - 2026-11-17

### Added
- XII: the floating sdlc launcher is the preferred wiring for every repo kind
(python-sdlc#62). `.sdlc/bin/sdlc` is committed and executable, the
`sdlc-commit` and `sdlc-push` hooks are `repo: local`, `language: system`,
`entry: .sdlc/bin/sdlc commit|push`, with no `rev:`, and the `sdlc ci` job
runs `.sdlc/bin/sdlc ci`. A repo in this form is judged by it alone, at any
`Inherits`. The rev-pinned python-sdlc hook and the standalone hooks are
still accepted until the fleet has converted. The launcher must hash to an
entry in `sdlc_bootstrap_sha256`, and the CI job must run that file, so a
repo cannot commit a script that passes itself. The `sdlc ci` step's `run`
must be exactly the launcher (no `|| true`), the job and step carry no
`if:` that could be false and no `continue-on-error`, and `SDLC_IMAGE` is
unset or `${{ vars.SDLC_IMAGE }}` at every `env:` level. A duplicate hook id
is reported. This repo's `Protect workflows` guard also covers `.sdlc/`. New `sdlc_launcher` and
`sdlc_bootstrap_sha256` keys; `sdlc` joins `floating_images`.
- XV rule 2: a third-party `uses:` names a full commit SHA, and a `docker://`
step an image digest; `crunchtools/*` and `./` are exempt. Report mode only:
the validator prints each unpinned reference as a warning (a GitHub
Expand Down
39 changes: 31 additions & 8 deletions constitution.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# CrunchTools Constitution

> **Version:** 1.45.0
> **Version:** 1.46.0
> **Ratified:** 2026-11-04
> **Status:** Active

Expand Down Expand Up @@ -344,7 +344,7 @@ Requiring two gates to run from containers said nothing about the rest. On a fre
A CI gate that only fires after the push finds problems once they are already someone else's review burden. Both gates therefore also run locally, before the commit exists.

**Rules:**
- A Python repo wires both gates through python-sdlc (below). Every other repo's `.pre-commit-config.yaml` MUST carry a hook with `id: gourmand` running `quay.io/crunchtools/gourmand` and a hook with `id: gatehouse` running `quay.io/crunchtools/gatehouse` with `--stdin` over `git diff --cached`, both from their container images. Copy them from `examples/pre-commit.yaml`.
- Every repo SHOULD wire both gates through the floating sdlc launcher (below), Python or not. Until the fleet has converted, a Python repo MAY instead pin python-sdlc, and any other repo's `.pre-commit-config.yaml` MUST otherwise carry a hook with `id: gourmand` running `quay.io/crunchtools/gourmand` and a hook with `id: gatehouse` running `quay.io/crunchtools/gatehouse` with `--stdin` over `git diff --cached`, both from their container images. Copy them from `examples/pre-commit.yaml`.
- Both hooks block the commit: Gourmand on any violation, Gatehouse on critical/high findings (exit `1`). The Gatehouse hook mounts the repo read-only so its Constitution agent reads the repo's own constitution. Its key comes from `~/.config/mcp-env/gatehouse.env`.
- `SKIP=gatehouse` (in a Python repo, `SDLC_SKIP=gatehouse`) is the escape hatch for a false positive. It does not make the finding go away: the same finding reappears on the PR and MUST be answered there (see Triage).

Expand All @@ -362,9 +362,29 @@ on the laptop and in CI alike.

**Rules:**
- A repo with a `pyproject.toml` is a Python repo. It MUST run its checks
through python-sdlc. Its hook `rev:` names one exact release (`vX.Y.Z`),
because pre-commit never refetches a moved tag; the image that release runs
is `latest` (XV rule 5):
through python-sdlc. Any repo MAY, and every repo SHOULD.
- **The floating form is preferred, for every repo kind.** The repo commits
python-sdlc's `bin/sdlc-bootstrap` as `.sdlc/bin/sdlc`, unchanged:
executable, not a symlink, and with a sha256 listed in
`sdlc_bootstrap_sha256`. The image floats; the file the gate trusts does
not, or a repo could commit a script that passes itself. Both hooks are `repo: local`, `language: system`, with
`entry: .sdlc/bin/sdlc commit` and `entry: .sdlc/bin/sdlc push`, and the push
hook runs at `pre-push`. There is no `rev:`: the bootstrap asks the image for
its own launcher, so the launcher and every tool float on `latest` together
(XV rule 5). The CI job `sdlc ci` runs that file, and nothing
else can make it green: the step's `run` is exactly `.sdlc/bin/sdlc ci`
(no `|| true`, no second line), neither the job nor the step carries an
`if:` that could be false or a `continue-on-error`, and `SDLC_IMAGE` is
unset or exactly `${{ vars.SDLC_IMAGE }}` at every `env:` level, because a
pull request must not choose the image that judges it. The `Protect
workflows` guard rejects fork changes under `.sdlc/` as well as
`.github/workflows/`. Copy both from
python-sdlc's `examples/`; `scripts/convert_repo.py` does the conversion.
A repo in this form is judged by it alone, whatever its kind or `Inherits`.
- Until the fleet has converted, the rev-pinned form is still accepted: a
hook block from `https://github.com/crunchtools/python-sdlc` whose `rev:`
names one exact release (`vX.Y.Z`), because pre-commit never refetches a
moved tag:

| Command | Runs | Config block in `pyproject.toml` |
|---|---|---|
Expand Down Expand Up @@ -408,9 +428,11 @@ on the laptop and in CI alike.
blocks every merge there instead.
- A release of Gourmand or Gatehouse triggers a python-sdlc release, which
moves `latest`, and every Python repo runs it on its next push and CI run,
with no pull request there. The laptop runs the reviewer CI runs. Only a
change to the launcher, `bin/sdlc`, needs a `rev:` bump.
- Exempt: `gourmand` and `python-sdlc`, which build what the image contains.
with no pull request there. The laptop runs the reviewer CI runs. In the
rev-pinned form only, a change to the launcher, `bin/sdlc`, needs a `rev:`
bump; the floating form never does.
- Exempt from requiring it: `gourmand` and `python-sdlc`, which build what
the image contains.
The list is `sdlc_exempt` in `requirements.toml`. Gatehouse is not exempt:
python-sdlc runs its last release, so it reviews its own changes the way the
standalone hook did.
Expand Down Expand Up @@ -958,5 +980,6 @@ a public repository. Keep it host-side (for example
| 1.43.0 | 2026-11-17 | On a user's machine the service tree lives in `~/Projects/<host>-services/<service>/`, backed up with `~/Projects`. Gatehouse leaves `sdlc_exempt`: python-sdlc runs its last release, as the standalone hook did, so it wires `sdlc-commit`, `sdlc-push` and `sdlc ci` like any Python repo once it pins this release. The XII `sdlc ci` job check accepts a quoted command. Prompted by crunchtools/gatehouse#133 (crunchtools/constitution#137) |
| 1.44.0 | 2026-11-17 | `container-release.yml` takes an opt-in `sign: true`: promote signs the gated digest with cosign v2 (`--tlog-upload=false`) in the `cosign-signing` environment before any tag moves, verified against `keys/crunchtools-bootc.pub`. Without it nothing changes. Prompted by crunchtools/rhel10-bootc-server#47: signing after promote left tags briefly unsigned and did not scale past the two bootc repos (crunchtools/constitution#142) |
| 1.45.0 | 2026-11-17 | Crunchtools refers to crunchtools at a moving tag (XV rule 5): the constitution's workflows are called at `@v1`, which `major-tag.yml` moves to each published release on main, as Gatehouse's `@v0` and Ashigaru's `@v2` already were; crunchtools tool images in hooks and CI name `:latest` (Gourmand `:main`) and a hook pulls with `--pull=newer`; pre-commit `rev:` and third-party pins stay exact. `Inherits` alone is the version a repo is judged by, so the validator accepts an older `Inherits` and new checks stay version-gated. Governance profile 1.1.0. Also: `container_release.py` refuses an off-branch `v*` tag before signing (#146). Prompted by every repo calling the constitution at v1.41.0 three releases behind, Gatehouse's review running its own unpushed image, and python-sdlc's hook running Gatehouse 0.23.0 (crunchtools/constitution#149) |
| 1.46.0 | 2026-11-17 | Floating sdlc launcher, no rev pin (Scott). XII prefers one wiring for every repo, Python or not: a committed `.sdlc/bin/sdlc` (python-sdlc's bootstrap, pinned by sha256 in `sdlc_bootstrap_sha256`) run by `repo: local` `sdlc-commit` and `sdlc-push` hooks with no `rev:`, and the `sdlc ci` job running exactly `.sdlc/bin/sdlc ci`, with no `if:`, no `continue-on-error`, and the image only from `vars.SDLC_IMAGE`. The image prints its own launcher, so hooks and CI float with it and no repo ever needs a `rev:` bump. The rev-pinned python-sdlc hook and the standalone Gourmand and Gatehouse hooks are still accepted until the fleet has converted. Accepting a form is not a new requirement, so it applies at any `Inherits`. `sdlc_launcher` in requirements.toml; `sdlc` joins `floating_images`. Also: XV rule 2 third-party pin report (#151). Prompted by crunchtools/python-sdlc#62, whose pilots (josui, mcp-nagios, syslog) failed `sdlc ci` on the constitution alone |
| 1.31.0 | 2026-11-04 | `sdlc ci` MUST be a required status check on the default branch, through an org ruleset rather than per-repo, and `fleet-drift.py` audits that ruleset's repo list against the repos XII applies to in both directions. Prompted by the v1.30.0 rollout: the conversion left the check advisory in all 33 repos, and auto-merge — Dependabot's and python-sdlc's own bump pull requests — merges on required checks alone, so a red `sdlc ci` would have landed every future bump. The reverse gap is as bad and had a live example: acquacotta's branch protection still required a `Python Tests` check the conversion had deleted, so a check that could never report again blocked every merge until it was found |
| 1.30.0 | 2026-11-04 | Python repos run their checks through python-sdlc (XII): one image, pinned at one release, three commands — `sdlc commit` at pre-commit, `sdlc push` at pre-push, `sdlc ci` in CI — each configured by the `pyproject.toml` block of the same name. Commit is seconds and offline; push renders the verdicts and never builds a container; CI runs push's checks except the two reviewers it gets from their own workflows, plus the repo's own. Repo checks are named kinds, never shell. Non-Python repos keep the standalone Gourmand and Gatehouse hooks. The validator requires the shape for repos inheriting v1.30.0, so a Python repo takes this version in the same pull request that converts it. Prompted by an audit of 35 Python repos (nine ruff versions, 15 with no type checker, 17 dependency scans that could not fail) and trentina's laptop running a two-week-old Gatehouse while CI ran a fresh one |
15 changes: 14 additions & 1 deletion profiles/requirements.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ gatehouse_min = "0.15.0"

# XV rule 5 since v1.45.0: a crunchtools tool image in a hook or a CI job names
# the tag its releases move. Gourmand cuts no releases, so it floats on `main`.
floating_images = { gatehouse = "latest", python-sdlc = "latest", gourmand = "main" }
# python-sdlc#62 renamed the image to `sdlc`; both names float until the old one is gone.
floating_images = { gatehouse = "latest", python-sdlc = "latest", sdlc = "latest", gourmand = "main" }

# XV rule 2: a third-party `uses:` names a full commit SHA (an image, a digest).
# "report" prints each one as a warning; "enforce" fails validation.
Expand All @@ -30,6 +31,18 @@ files = ["CHANGELOG.md", ".pre-commit-config.yaml", ".github/dependabot.yml"]
sdlc_hooks_repo = "https://github.com/crunchtools/python-sdlc"
sdlc_hooks = ["sdlc-commit", "sdlc-push"]
sdlc_exempt = ["gourmand", "python-sdlc"]
# Since v1.46.0 the preferred wiring for every repo, Python or not: `repo: local`
# hooks whose entry is this committed launcher (python-sdlc's bin/sdlc-bootstrap),
# with no `rev:`. It asks the image for its own runner, so nothing pins a release.
# The rev-pinned and standalone forms above are accepted until the fleet converts.
sdlc_launcher = ".sdlc/bin/sdlc"
# The bootstrap releases that launcher may be, by sha256. The image floats; the
# file a gate trusts does not, or a repo could commit a script that passes
# itself. A new bin/sdlc-bootstrap adds its hash here; old ones stay until the
# fleet has moved off them.
sdlc_bootstrap_sha256 = [
"6c4691c4aea0be66d6a6acd2efdf191a5038a1b3b8396b2fc60d14cd419eca72", # python-sdlc#62 at a483867
]

# Container release (container-image VII, since 1.39.0, RT#1550): repos that
# keep their own promote workflow instead of calling container-release.yml.
Expand Down
62 changes: 62 additions & 0 deletions tests/sdlc-bootstrap
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
#!/bin/sh
# Run `sdlc` with no `rev:` to pin: get the launcher from the image, then run it.
#
# The launcher (bin/sdlc) ships inside quay.io/crunchtools/sdlc, so it floats
# with the image tag exactly as the tools in the image do: `:latest` by
# default, SDLC_IMAGE=main for what has merged and not been released, a
# release such as SDLC_IMAGE=0.9.0, or SDLC_IMAGE=@sha256:<digest>. Nothing
# else: this file runs whatever it pulls, so it pulls from that one repository.
# A seat trying a local build runs a python-sdlc clone's bin/sdlc instead. The
# image prints the launcher with its own ref written into it (`sdlc launcher
# <ref>`), so the launcher and the image it starts cannot disagree.
#
# A converted repo carries this file as .sdlc/bin/sdlc, and its hooks and its
# CI job run it (scripts/convert_repo.py writes it). Nothing in it names a
# release, so nothing ever bumps it, and the constitution pins its bytes. An
# `sdlc` RPM would install the same file as /usr/bin/sdlc.
#
# Host contract: podman and POSIX sh, nothing else. Never a pipe into `sh`: a
# failed pull would hand sh nothing, and nothing runs and exits 0. An image
# that cannot print its launcher is a 2 -- the gate could not run.

set -u

FLEET=quay.io/crunchtools/sdlc
refuse() {
printf 'sdlc: GATE CANNOT RUN: SDLC_IMAGE=%s is not main, latest, X.Y.Z or @sha256:<64 hex> of %s\n' \
"${SDLC_IMAGE:-}" "$FLEET" >&2
exit 2
}

# The value, with the repository named in full or not at all.
want=${SDLC_IMAGE:-latest}
case $want in

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Test Coverage): The new image-reference allowlist has multiple parsing and rejection branches, but no tests were added or updated to cover them. Regressions could accept an unintended reference or reject a supported one without detection.

Suggestion: Add table-driven shell tests for main, latest, version refs, fully qualified refs, and valid digests, plus rejected refs and digest length/character boundary cases. Mock the pull command to verify invalid values are rejected before any image is pulled.

Evidence:

case $want in
  main|latest) image=$FLEET:$want ;;
  @sha256:*)
    hex=${want#@sha256:}
    case $hex in *[!0-9a-f]*) refuse ;; esac
    [ "${#hex}" -eq 64 ] || refuse
    image=$FLEET$want ;;
  *[!0-9.]*|.*|*.|*..*|*.*.*.*) refuse ;;
  *.*.*) image=$FLEET:$want ;;
  *) refuse ;;
esac

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a bug: tests/sdlc-bootstrap is a byte-for-byte fixture of python-sdlc's bin/sdlc-bootstrap at a483867, kept here only so the validator's sha256 pin is tested against real bytes; this repo never runs it. The image-ref allowlist this finding asks about is table-tested at its source, python-sdlc a483867 tests/test_host_contract.sh ("the floating launcher" section). It covers main, X.Y.Z, @sha256 and fully qualified refs as accepted. It covers localhost/, other repos, 1.2, v1.2.3, 1.2.3.4, 1..3, a short or non-hex digest, main;id and --privileged as refused with exit 2 before podman runs.

"$FLEET":*) want=${want#"$FLEET":} ;;
"$FLEET"@*) want=${want#"$FLEET"} ;;
esac
case $want in
main|latest) image=$FLEET:$want ;;
@sha256:*)
hex=${want#@sha256:}
case $hex in *[!0-9a-f]*) refuse ;; esac
[ "${#hex}" -eq 64 ] || refuse
image=$FLEET$want ;;
*[!0-9.]*|.*|*.|*..*|*.*.*.*) refuse ;;
*.*.*) image=$FLEET:$want ;;
*) refuse ;;
esac

dir=$(mktemp -d) || exit 2
trap 'rm -rf "$dir"' EXIT
trap 'exit 2' HUP INT TERM

# --pull=newer: :latest moves, and a stale local copy is how a two-week-old
# reviewer once judged trentina. Offline, podman keeps the copy it has.
if ! podman --events-backend=none run --rm --log-driver=none --network=none \

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MEDIUM (Test Coverage): The new bootstrap script invokes an external podman command, handles pull and empty-output failures, writes a temporary launcher, and forwards arguments and the launcher’s exit status, but no tests exercise these paths. Failures in this gate-running script could therefore go undetected.

Suggestion: Add shell-level tests using a stub podman executable to cover successful launcher retrieval and argument forwarding, command failure, empty output, and propagation of the launcher’s exit status.

Evidence:

if ! podman --events-backend=none run --rm --log-driver=none --network=none \
       --cap-drop=all --security-opt=no-new-privileges --pull=newer \
       -- "$image" launcher "$image" > "$dir/sdlc" || [ ! -s "$dir/sdlc" ]; then
  ...
fi
sh "$dir/sdlc" "$@"

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a bug: tests/sdlc-bootstrap is a byte-for-byte fixture of python-sdlc's bin/sdlc-bootstrap, kept here only so the validator's sha256 pin is tested against real bytes; this repo never runs it. Its behaviour (stub podman, pull failure, empty output, argv and exit status) is tested where it lives, in python-sdlc#62's tests/test_host_contract.sh and tests/contract.sh.

--cap-drop=all --security-opt=no-new-privileges --pull=newer \
-- "$image" launcher "$image" > "$dir/sdlc" || [ ! -s "$dir/sdlc" ]; then
printf 'sdlc: GATE CANNOT RUN: %s could not print its launcher\n' "$image" >&2
exit 2
fi
# The launcher reads SDLC_IMAGE too; it gets the full reference checked here.
SDLC_IMAGE=$image sh "$dir/sdlc" "$@"
2 changes: 1 addition & 1 deletion tests/test_cascade.py
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ def test_a_direct_dispatch_counts():

CALLER = (
"jobs:\n container:\n"
" uses: crunchtools/constitution/.github/workflows/container-release.yml@v1.45.0\n"
" uses: crunchtools/constitution/.github/workflows/container-release.yml@v1.46.0\n"
" with:\n cascade: true\n downstream: child other-child\n"
)

Expand Down
Loading
Loading