diff --git a/.github/workflows/container-release.yml b/.github/workflows/container-release.yml index 936b195..792dc4a 100644 --- a/.github/workflows/container-release.yml +++ b/.github/workflows/container-release.yml @@ -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 @@ -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' @@ -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: @@ -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 diff --git a/.github/workflows/dependency-audit.yml b/.github/workflows/dependency-audit.yml index 44303b3..5f78146 100644 --- a/.github/workflows/dependency-audit.yml +++ b/.github/workflows/dependency-audit.yml @@ -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 diff --git a/.github/workflows/gatehouse.yml b/.github/workflows/gatehouse.yml index ea771bb..ee4a244 100644 --- a/.github/workflows/gatehouse.yml +++ b/.github/workflows/gatehouse.yml @@ -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. @@ -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 \ diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index c986b3f..7c27370 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index d61a1b5..b3d2f9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/constitution.md b/constitution.md index 2839b15..feb5f40 100644 --- a/constitution.md +++ b/constitution.md @@ -1,6 +1,6 @@ # CrunchTools Constitution -> **Version:** 1.45.0 +> **Version:** 1.46.0 > **Ratified:** 2026-11-04 > **Status:** Active @@ -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). @@ -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` | |---|---|---| @@ -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. @@ -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/-services//`, 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 | diff --git a/profiles/requirements.toml b/profiles/requirements.toml index bd939f5..9143477 100644 --- a/profiles/requirements.toml +++ b/profiles/requirements.toml @@ -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. @@ -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. diff --git a/tests/sdlc-bootstrap b/tests/sdlc-bootstrap new file mode 100755 index 0000000..6fbb342 --- /dev/null +++ b/tests/sdlc-bootstrap @@ -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:. 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 +# `), 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 + "$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 \ + --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" "$@" diff --git a/tests/test_cascade.py b/tests/test_cascade.py index 6b6ed7c..246e765 100644 --- a/tests/test_cascade.py +++ b/tests/test_cascade.py @@ -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" ) diff --git a/tests/test_manifest.py b/tests/test_manifest.py index 2d57f4c..d551690 100644 --- a/tests/test_manifest.py +++ b/tests/test_manifest.py @@ -854,6 +854,223 @@ def test_a_quoted_or_bare_sdlc_ci_counts(repo, run): assert not [v for v in violations(repo) if "sdlc ci" in v] +# XII since v1.46.0: the floating launcher, preferred for every repo (python-sdlc#62). + +FLOATING = """default_install_hook_types: [pre-commit, pre-push] + +repos: + - repo: local + hooks: + - id: sdlc-commit + entry: .sdlc/bin/sdlc commit + language: system + stages: [pre-commit, pre-merge-commit] + - id: sdlc-push + entry: .sdlc/bin/sdlc push + language: system + stages: [pre-push] +""" + + +# python-sdlc's bin/sdlc-bootstrap from python-sdlc#62, byte for byte: the +# validator accepts only a launcher whose sha256 is in requirements.toml. +BOOTSTRAP = (Path(__file__).parent / "sdlc-bootstrap").read_text() + + +def float_repo(root: Path) -> None: + write(root, ".pre-commit-config.yaml", FLOATING) + write(root, ".sdlc/bin/sdlc", BOOTSTRAP) + (root / ".sdlc/bin/sdlc").chmod(0o755) + write(root, ".github/workflows/ci.yml", SDLC_CI.replace("bin/sdlc ci", ".sdlc/bin/sdlc ci")) + + +def test_a_python_repo_on_the_floating_launcher_passes(repo): + float_repo(repo) + assert violations(repo) == [] + + +def test_a_non_python_repo_on_the_floating_launcher_passes(repo): + """syslog, a container-only repo, converts too: no standalone hooks needed.""" + (repo / "pyproject.toml").unlink() + float_repo(repo) + assert not [v for v in violations(repo) if v.startswith("XII")] + + +@pytest.mark.parametrize("old", ["1.17.0", "1.41.0"]) +def test_the_floating_launcher_needs_no_inherits_bump(repo, old): + """Accepting a form is not a new requirement, so it is not version-gated.""" + inherit(repo, old) + float_repo(repo) + assert not [v for v in violations(repo) if v.startswith("XII")] + + +def test_the_launcher_must_be_committed(repo): + float_repo(repo) + (repo / ".sdlc/bin/sdlc").unlink() + assert any("not a file in this repo" in v for v in violations(repo)) + + +def test_the_launcher_must_not_be_a_symlink(repo): + float_repo(repo) + target = repo / "elsewhere" + (repo / ".sdlc/bin/sdlc").rename(target) + (repo / ".sdlc/bin/sdlc").symlink_to(target) + assert any("not a file in this repo" in v for v in violations(repo)) + + +def test_the_launcher_must_be_executable(repo): + float_repo(repo) + (repo / ".sdlc/bin/sdlc").chmod(0o644) + [found] = violations(repo) + assert "is not executable" in found + + +@pytest.mark.parametrize( + "launcher", ["#!/bin/sh\nexit 0\n", BOOTSTRAP.replace("exit 2", "exit 0"), BOOTSTRAP + "\n"] +) +def test_a_launcher_that_is_not_a_bootstrap_release_fails(repo, launcher): + """A committed script that exits 0 would let a repo pass its own gate.""" + float_repo(repo) + write(repo, ".sdlc/bin/sdlc", launcher) + [found] = violations(repo) + assert "is not a python-sdlc bootstrap release" in found + + +@pytest.mark.parametrize( + "run", + [ + "bin/sdlc ci", + "./tools/sdlc ci", + "sdlc ci", + ".sdlc/bin/sdlc ci || true", + "|\n .sdlc/bin/sdlc ci\n exit 0", + ], +) +def test_a_floating_repo_ci_must_run_the_committed_launcher(repo, run): + """The hooks run the pinned bootstrap; CI judging with another sdlc defeats it.""" + float_repo(repo) + write(repo, ".github/workflows/ci.yml", SDLC_CI.replace("bin/sdlc ci", run)) + [found] = violations(repo) + assert "run is exactly `.sdlc/bin/sdlc ci`" in found + + +FLOAT_CI = """name: CI +on: pull_request +{wf_env}jobs: + sdlc: + name: sdlc ci + runs-on: ubuntu-latest +{job_extra} steps: + - name: sdlc ci +{step_extra} run: .sdlc/bin/sdlc ci +""" + + +def float_ci(repo: Path, wf_env: str = "", job_extra: str = "", step_extra: str = "") -> None: + write( + repo, + ".github/workflows/ci.yml", + FLOAT_CI.format(wf_env=wf_env, job_extra=job_extra, step_extra=step_extra), + ) + + +@pytest.mark.parametrize( + "where", ["step_extra", "job_extra", "wf_env"], ids=["step", "job", "workflow"] +) +@pytest.mark.parametrize("image", ["ghcr.io/attacker/sdlc:evil", "main", "${{ env.X }}"]) +def test_a_floating_ci_image_comes_only_from_the_variable(repo, where, image): + """A pull request must not choose the image that judges it (#157 B2).""" + float_repo(repo) + indent = {"step_extra": 8, "job_extra": 4, "wf_env": 0}[where] + pad = " " * indent + float_ci(repo, **{where: f"{pad}env:\n{pad} SDLC_IMAGE: '{image}'\n"}) + [found] = violations(repo) + assert "sets SDLC_IMAGE" in found + + +def test_the_repository_variable_may_choose_the_image(repo): + float_repo(repo) + float_ci(repo, step_extra=" env:\n SDLC_IMAGE: ${{ vars.SDLC_IMAGE }}\n") + assert violations(repo) == [] + + +@pytest.mark.parametrize( + ("where", "line"), + [ + ("job_extra", " if: false\n"), + ("job_extra", " if: github.actor != 'x'\n"), + ("job_extra", " continue-on-error: true\n"), + ("step_extra", " if: false\n"), + ("step_extra", " continue-on-error: ${{ true }}\n"), + ], +) +def test_the_floating_sdlc_ci_job_always_runs_and_counts(repo, where, line): + """A skipped required check reads as passed; a tolerated failure as green.""" + float_repo(repo) + float_ci(repo, **{where: line}) + [found] = violations(repo) + assert "`if:` or `continue-on-error`" in found + + +def test_an_if_that_is_always_true_is_allowed(repo): + float_repo(repo) + float_ci(repo, job_extra=" if: true\n", step_extra=" continue-on-error: false\n") + assert violations(repo) == [] + + +def test_a_duplicate_floating_hook_is_named(repo): + float_repo(repo) + write( + repo, + ".pre-commit-config.yaml", + FLOATING + + " - id: sdlc-push\n entry: .sdlc/bin/sdlc push\n" + + " language: system\n stages: [pre-push]\n", + ) + [found] = violations(repo) + assert "more than one hook is `sdlc-push`" in found + + +@pytest.mark.parametrize("hook", ["sdlc-commit", "sdlc-push"]) +def test_a_floating_repo_needs_both_hooks(repo, hook): + float_repo(repo) + write(repo, ".pre-commit-config.yaml", FLOATING.replace(f"id: {hook}", "id: other")) + [found] = violations(repo) + assert f"no `{hook}` hook" in found + + +@pytest.mark.parametrize( + ("old", "new", "message"), + [ + (".sdlc/bin/sdlc push", ".sdlc/bin/sdlc commit", "`entry: .sdlc/bin/sdlc push`"), + ( + "sdlc push\n language: system", + "sdlc push\n language: script", + "language: system", + ), + ("stages: [pre-push]", "stages: [pre-commit]", "does not run at `pre-push`"), + ("[pre-commit, pre-push]", "[pre-commit]", "does not name `pre-push`"), + ], +) +def test_a_floating_hook_must_run_what_its_name_says(repo, old, new, message): + float_repo(repo) + write(repo, ".pre-commit-config.yaml", FLOATING.replace(old, new, 1)) + assert any(message in v for v in violations(repo)) + + +def test_a_floating_repo_must_run_sdlc_ci(repo): + float_repo(repo) + (repo / ".github/workflows/ci.yml").unlink() + [found] = violations(repo) + assert "no CI job named `sdlc ci`" in found + + +def test_a_dotted_launcher_path_counts(repo): + float_repo(repo) + write(repo, ".pre-commit-config.yaml", FLOATING.replace("entry: .sdlc", "entry: ./.sdlc")) + assert violations(repo) == [] + + # The outbound HTTP contract (MCP Server profile 1.8.0, RT #1601). The fixture # repo carries no `src/`, so the check skips it and every test above stays green; # each test here adds a client and breaks one thing about it. diff --git a/validate-constitution.py b/validate-constitution.py index 6b343dd..63eda22 100755 --- a/validate-constitution.py +++ b/validate-constitution.py @@ -18,6 +18,7 @@ import argparse import ast +import hashlib import json import os import re @@ -358,8 +359,146 @@ def is_sdlc_repo(repo_root: Path, inherits: str | None, requirements: dict) -> b ) +def floating_sdlc_hooks(config: dict, launcher: str) -> dict[str, dict]: + """The `repo: local` hooks whose entry runs the committed launcher, by id. + + A second hook with an id already seen is kept as `#2`, so it counts as + neither hook and the check names it, instead of silently using one. + """ + found: dict[str, dict] = {} + for source in config.get("repos") or []: + if not isinstance(source, dict) or source.get("repo") != "local": + continue + for hook in source.get("hooks") or []: + if not isinstance(hook, dict): + continue + words = str(hook.get("entry", "")).split() + if words and words[0].removeprefix("./") == launcher: + key = str(hook.get("id")) + found[f"{key}#2" if key in found else key] = hook + return found + + +def check_install_hook_types(config: dict) -> list[str]: + """Parsed, not matched: the indented block form of this list is as legal as + the inline one, and a line match sees only the first entry.""" + declared = config.get("default_install_hook_types") or [] + declared = declared if isinstance(declared, list) else [declared] + return [ + f"XII: `default_install_hook_types` does not name `{stage}`, so " + f"`pre-commit install` never wires that hook" + for stage in ("pre-commit", "pre-push") + if stage not in declared + ] + + +def check_floating_wiring(repo_root: Path, config: dict, requirements: dict) -> list[str]: + """XII since v1.46.0, any repo: the committed launcher, both hooks, the CI job. + + Nothing pins a release: the launcher asks the image for its own runner, so + hooks and CI float with the image (python-sdlc#62). What floats is the + image, not the launcher: a committed file the gate trusts must be one + python-sdlc shipped, or a repo grades itself. + """ + fleet = requirements.get("fleet", {}) + launcher = fleet.get("sdlc_launcher", ".sdlc/bin/sdlc") + path = repo_root / launcher + violations = [] + if path.is_symlink() or not path.is_file(): + violations.append(f"XII: the hooks run `{launcher}`, which is not a file in this repo") + elif not os.access(path, os.X_OK): + violations.append(f"XII: `{launcher}` is not executable") + elif hashlib.sha256(path.read_bytes()).hexdigest() not in fleet.get( + "sdlc_bootstrap_sha256", [] + ): + violations.append( + f"XII: `{launcher}` is not a python-sdlc bootstrap release " + f"(copy bin/sdlc-bootstrap unchanged, or run its scripts/convert_repo.py)" + ) + hooks = floating_sdlc_hooks(config, launcher) + violations += [ + f"XII: more than one hook is `{key.removesuffix('#2')}`; keep one" + for key in hooks + if key.endswith("#2") + ] + for hook_id, stage in (("sdlc-commit", "pre-commit"), ("sdlc-push", "pre-push")): + hook = hooks.get(hook_id) + command = hook_id.removeprefix("sdlc-") + if hook is None: + violations.append( + f"XII: .pre-commit-config.yaml has no `{hook_id}` hook running " + f"`{launcher} {command}`" + ) + continue + words = str(hook.get("entry", "")).split() + if words[1:] != [command] or hook.get("language") != "system": + violations.append( + f"XII: the `{hook_id}` hook must be `language: system` with " + f"`entry: {launcher} {command}`" + ) + stages = hook.get("stages") or ["pre-commit"] + if stage not in stages: + violations.append(f"XII: the `{hook_id}` hook does not run at `{stage}`") + violations += check_install_hook_types(config) + violations += check_floating_ci(repo_root, launcher) + return violations + + +def _always_runs(block: dict) -> bool: + """No `if:` that could be false, and no `continue-on-error` that could be true.""" + condition = block.get("if", True) + tolerated = block.get("continue-on-error", False) + return condition in (True, "true") and tolerated in (False, "false") + + +def check_floating_ci(repo_root: Path, launcher: str) -> list[str]: + """The `sdlc ci` job in the floating form: it runs the launcher, and only that. + + The job is the required check, so anything that lets it go green without + judging is a hole: a step that runs something else or swallows the exit + (`|| true`), an `if:` that skips it (a skipped required check counts as + passed), `continue-on-error`, or an image a pull request names itself. + SDLC_IMAGE comes from the repository variable, which only an admin sets. + """ + wanted = {f"{launcher} ci", f"./{launcher} ci"} + violations: list[str] = [] + found = False + for path in workflow_files(repo_root): + workflow = load_yaml(path) or {} + jobs = workflow.get("jobs") if isinstance(workflow, dict) else None + for job in (jobs or {}).values(): + if not isinstance(job, dict) or job.get("name") != "sdlc ci": + continue + steps = [step for step in job.get("steps") or [] if isinstance(step, dict)] + runs = [step for step in steps if str(step.get("run", "")).strip() in wanted] + found = found or bool(runs) + where = f"{path.name}: the `sdlc ci` job" + if not _always_runs(job): + violations.append(f"XII: {where} has an `if:` or `continue-on-error`") + violations += [ + f"XII: {where} runs `{launcher} ci` under an `if:` or `continue-on-error`" + for step in runs + if not _always_runs(step) + ] + for scope in (workflow, job, *runs): + image = (scope.get("env") or {}).get("SDLC_IMAGE") + if image is not None and str(image).strip() != "${{ vars.SDLC_IMAGE }}": + violations.append( + f"XII: {where} sets SDLC_IMAGE to `{image}`; only " + f"`${{{{ vars.SDLC_IMAGE }}}}` may choose the image" + ) + if not found: + violations.append( + f"XII: no CI job named `sdlc ci` has a step whose run is exactly `{launcher} ci`" + ) + return violations + + def check_sdlc_wiring(repo_root: Path, hooks: str, requirements: dict) -> list[str]: - """XII since v1.30.0: python-sdlc at one exact release, both hooks, the CI job.""" + """XII since v1.30.0: python-sdlc at one exact release, both hooks, the CI job. + + Superseded by check_floating_wiring; accepted until the fleet has converted. + """ fleet = requirements.get("fleet", {}) url = fleet.get("sdlc_hooks_repo", "https://github.com/crunchtools/python-sdlc") block = re.search( @@ -379,17 +518,7 @@ def check_sdlc_wiring(repo_root: Path, hooks: str, requirements: dict) -> list[s for hook in fleet.get("sdlc_hooks", ["sdlc-commit", "sdlc-push"]) if not re.search(rf"-\s*id:\s*{re.escape(hook)}[ \t]*$", block.group(1), re.M) ] - # Parsed, not matched: the indented block form of this list is as legal as - # the inline one, and a line match sees only the first entry. - parsed = load_yaml(repo_root / ".pre-commit-config.yaml") or {} - declared = parsed.get("default_install_hook_types") or [] - declared = declared if isinstance(declared, list) else [declared] - violations += [ - f"XII: `default_install_hook_types` does not name `{stage}`, so " - f"`pre-commit install` never wires that hook" - for stage in ("pre-commit", "pre-push") - if stage not in declared - ] + violations += check_install_hook_types(load_yaml(repo_root / ".pre-commit-config.yaml") or {}) if not any(_runs_sdlc_ci(load_yaml(f) or {}) for f in workflow_files(repo_root)): violations.append("XII: no CI job named `sdlc ci` runs the `sdlc ci` command") return violations @@ -444,9 +573,10 @@ def check_quality_gate_wiring( """XII since 1.17.0: the local gates, and the Gatehouse triage job. Reads the real files, like check_gourmand_ci_gate: prose saying a gate - exists is exactly what let the gates rot before. Since v1.30.0 a Python - repo's gates come from python-sdlc; every other repo's from the standalone - hooks. + exists is exactly what let the gates rot before. Since v1.46.0 any repo + whose hooks run the committed launcher is judged by that form alone. Until + the fleet has converted, a Python repo may still pin python-sdlc (v1.30.0) + and every other repo carry the standalone hooks. """ if repo_root is None or _version_tuple(inherits) < GATES_SINCE: return [] @@ -456,7 +586,12 @@ def check_quality_gate_wiring( violations: list[str] = [] config = repo_root / ".pre-commit-config.yaml" hooks = strip_yaml_comments(config.read_text()) if config.is_file() else "" - if is_sdlc_repo(repo_root, inherits, requirements): + parsed = load_yaml(config) if config.is_file() else None + parsed = parsed if isinstance(parsed, dict) else {} + launcher = requirements.get("fleet", {}).get("sdlc_launcher", ".sdlc/bin/sdlc") + if floating_sdlc_hooks(parsed, launcher): + violations += check_floating_wiring(repo_root, parsed, requirements) + elif is_sdlc_repo(repo_root, inherits, requirements): violations += check_sdlc_wiring(repo_root, hooks, requirements) else: violations += check_standalone_hooks(hooks)