From 260304144e429cc4c3be6ff439b3549125be47b3 Mon Sep 17 00:00:00 2001 From: Josui Date: Tue, 17 Nov 2026 20:54:16 +0000 Subject: [PATCH 1/5] feat: accept the floating sdlc launcher in XII; constitution 1.46.0 python-sdlc#62 converts repos to a committed bootstrap, .sdlc/bin/sdlc, run by repo: local hooks with no rev: and by the sdlc ci job. Every converted pilot (josui, mcp-nagios, syslog) failed sdlc ci on the constitution alone: check_sdlc_wiring demanded the rev-pinned hook and check_standalone_hooks the Gourmand/Gatehouse hooks. XII now prefers the floating form for every repo kind. A repo whose hooks run the launcher is judged by check_floating_wiring alone: the launcher is a committed executable file, sdlc-commit and sdlc-push are language: system with the right entry and stage, both hook types are installed, and a job named `sdlc ci` runs it. Accepting a form is not a new requirement, so it is not version-gated. The rev-pinned and standalone forms stay accepted until the wave finishes. Releases 1.46.0 (1.43.0 was already taken): refs, CHANGELOG, history row. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN --- .github/workflows/container-release.yml | 8 +- .github/workflows/dependency-audit.yml | 2 +- .github/workflows/validate.yml | 2 +- CHANGELOG.md | 10 +++ constitution.md | 30 +++++-- profiles/requirements.toml | 8 +- tests/test_cascade.py | 2 +- tests/test_manifest.py | 106 ++++++++++++++++++++++++ validate-constitution.py | 98 ++++++++++++++++++---- 9 files changed, 234 insertions(+), 32 deletions(-) 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/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..e485f21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,17 @@ 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. New `sdlc_launcher` key; + `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..82bfc04 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,20 @@ 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` (executable, not a + symlink). 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 `.sdlc/bin/sdlc ci`. 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 +419,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 +971,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) run by `repo: local` `sdlc-commit` and `sdlc-push` hooks with no `rev:`, and the `sdlc ci` job running `.sdlc/bin/sdlc ci`. 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..bd5c798 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,11 @@ 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" # 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/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..91497da 100644 --- a/tests/test_manifest.py +++ b/tests/test_manifest.py @@ -854,6 +854,112 @@ 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] +""" + + +def float_repo(root: Path) -> None: + write(root, ".pre-commit-config.yaml", FLOATING) + write(root, ".sdlc/bin/sdlc", "#!/bin/sh\n") + (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("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..dff2d02 100755 --- a/validate-constitution.py +++ b/validate-constitution.py @@ -358,8 +358,78 @@ 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.""" + found = {} + 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: + found[str(hook.get("id"))] = 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). + """ + 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") + hooks = floating_sdlc_hooks(config, launcher) + 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) + 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 + + 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 +449,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 +504,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 +517,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) From 371e59d39a90c8f06e06470671646800d326d0f5 Mon Sep 17 00:00:00 2001 From: Josui Date: Tue, 17 Nov 2026 21:05:32 +0000 Subject: [PATCH 2/5] fix(validator): a floating launcher must be a pinned bootstrap release Any executable at .sdlc/bin/sdlc passed, so a repo could commit a script that exits 0 and pass its own hooks and its `sdlc ci` required check. The launcher must now hash to an entry in sdlc_bootstrap_sha256 (python-sdlc#62's bin/sdlc-bootstrap), and in the floating form the `sdlc ci` job must run that committed file, not any `sdlc` on a path. The image still floats; only the file the gate trusts is pinned. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN --- CHANGELOG.md | 6 ++++-- constitution.md | 10 ++++++---- profiles/requirements.toml | 7 +++++++ tests/sdlc-bootstrap | 40 ++++++++++++++++++++++++++++++++++++++ tests/test_manifest.py | 27 ++++++++++++++++++++++++- validate-constitution.py | 24 +++++++++++++++++------ 6 files changed, 101 insertions(+), 13 deletions(-) create mode 100755 tests/sdlc-bootstrap diff --git a/CHANGELOG.md b/CHANGELOG.md index e485f21..8aa1972 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,8 +18,10 @@ Entries through 1.14.0 are derived from the Ratification History table in `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. New `sdlc_launcher` key; - `sdlc` joins `floating_images`. + 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. 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 82bfc04..4da6bfe 100644 --- a/constitution.md +++ b/constitution.md @@ -364,12 +364,14 @@ on the laptop and in CI alike. - A repo with a `pyproject.toml` is a Python repo. It MUST run its checks 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` (executable, not a - symlink). Both hooks are `repo: local`, `language: system`, with + 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 `.sdlc/bin/sdlc ci`. Copy both from + (XV rule 5). The CI job `sdlc ci` runs that file, `.sdlc/bin/sdlc ci`. 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 @@ -971,6 +973,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) run by `repo: local` `sdlc-commit` and `sdlc-push` hooks with no `rev:`, and the `sdlc ci` job running `.sdlc/bin/sdlc ci`. 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.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 `.sdlc/bin/sdlc ci`. 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 bd5c798..8300923 100644 --- a/profiles/requirements.toml +++ b/profiles/requirements.toml @@ -36,6 +36,13 @@ sdlc_exempt = ["gourmand", "python-sdlc"] # 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 = [ + "87e8649a0724b40e68d2e3f331fb5b3dca5b9b8adb29254f2e88bc9c9c2cd6c1", # python-sdlc#62 +] # 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..6be5056 --- /dev/null +++ b/tests/sdlc-bootstrap @@ -0,0 +1,40 @@ +#!/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 any full ref such as a seat's localhost/ +# build. 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. 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 + +image=${SDLC_IMAGE:-latest} +case $image in + */*) ;; + *) image=quay.io/crunchtools/sdlc:$image ;; +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 +sh "$dir/sdlc" "$@" diff --git a/tests/test_manifest.py b/tests/test_manifest.py index 91497da..360b48a 100644 --- a/tests/test_manifest.py +++ b/tests/test_manifest.py @@ -872,9 +872,14 @@ def test_a_quoted_or_bare_sdlc_ci_counts(repo, run): """ +# 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", "#!/bin/sh\n") + 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")) @@ -920,6 +925,26 @@ def test_the_launcher_must_be_executable(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"]) +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 "runs `.sdlc/bin/sdlc ci`" in found + + @pytest.mark.parametrize("hook", ["sdlc-commit", "sdlc-push"]) def test_a_floating_repo_needs_both_hooks(repo, hook): float_repo(repo) diff --git a/validate-constitution.py b/validate-constitution.py index dff2d02..8cea6bb 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 @@ -390,7 +391,9 @@ def check_floating_wiring(repo_root: Path, config: dict, requirements: dict) -> """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). + 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") @@ -400,6 +403,13 @@ def check_floating_wiring(repo_root: Path, config: dict, requirements: dict) -> 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) for hook_id, stage in (("sdlc-commit", "pre-commit"), ("sdlc-push", "pre-push")): hook = hooks.get(hook_id) @@ -420,8 +430,8 @@ def check_floating_wiring(repo_root: Path, config: dict, requirements: dict) -> if stage not in stages: violations.append(f"XII: the `{hook_id}` hook does not run at `{stage}`") violations += check_install_hook_types(config) - 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") + if not any(_runs_sdlc_ci(load_yaml(f) or {}, launcher) for f in workflow_files(repo_root)): + violations.append(f"XII: no CI job named `sdlc ci` runs `{launcher} ci`") return violations @@ -455,13 +465,15 @@ def check_sdlc_wiring(repo_root: Path, hooks: str, requirements: dict) -> list[s return violations -def _runs_sdlc_ci(workflow: dict) -> bool: +def _runs_sdlc_ci(workflow: dict, launcher: str | None = None) -> bool: """A JOB named `sdlc ci` whose steps run the `sdlc ci` command. Parsed, not matched: a regex for `name: sdlc ci` is satisfied by a workflow's or a step's name just as well as a job's, and a job carrying the - right name while running something else would pass it too. + right name while running something else would pass it too. With a + `launcher`, the command must be that committed file, not any `sdlc`. """ + command = rf"(?:\./)?{re.escape(launcher)}" if launcher else r"[\"']?(?:\S*/)?sdlc[\"']?" 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": @@ -471,7 +483,7 @@ def _runs_sdlc_ci(workflow: dict) -> bool: # The command word of a line must be `sdlc` (by any path), so # `echo sdlc ci` does not count as running it. The command may be # quoted, as a path held in a variable should be. - if re.search(r"^\s*[\"']?(?:\S*/)?sdlc[\"']?\s+ci\b", str(run), re.M): + if re.search(rf"^\s*{command}\s+ci\b", str(run), re.M): return True return False From db3384cfe218236e421a1d310a9b9d511a6703bf Mon Sep 17 00:00:00 2001 From: Josui Date: Tue, 17 Nov 2026 21:10:12 +0000 Subject: [PATCH 3/5] fix(validator): the floating sdlc ci job runs the launcher and only that From #157's review (a213). The `sdlc ci` job is the required check, so anything that turns it green without judging is a hole: - the step's run must be exactly `.sdlc/bin/sdlc ci`, so `|| true`, a second line and another script are rejected - no `if:` that could be false and no `continue-on-error` on the job or the step: a skipped required check reads as passed - SDLC_IMAGE unset or exactly `${{ vars.SDLC_IMAGE }}` at workflow, job and step env (B2): a PR must not choose the image that judges it - a duplicate floating hook id is named instead of silently replacing - this repo's Protect workflows guard also rejects fork changes to .sdlc/ Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN --- .github/workflows/gatehouse.yml | 7 +-- CHANGELOG.md | 6 ++- constitution.md | 11 +++- tests/test_manifest.py | 90 ++++++++++++++++++++++++++++++++- validate-constitution.py | 77 ++++++++++++++++++++++++---- 5 files changed, 173 insertions(+), 18 deletions(-) diff --git a/.github/workflows/gatehouse.yml b/.github/workflows/gatehouse.yml index ea771bb..032fdf9 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. @@ -69,8 +70,8 @@ jobs: # path, so a fork could move a workflow out of .github/workflows/ 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/CHANGELOG.md b/CHANGELOG.md index 8aa1972..b3d2f9c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,7 +20,11 @@ Entries through 1.14.0 are derived from the Ratification History table in `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. New `sdlc_launcher` and + 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: diff --git a/constitution.md b/constitution.md index 4da6bfe..feb5f40 100644 --- a/constitution.md +++ b/constitution.md @@ -371,7 +371,14 @@ on the laptop and in CI alike. `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, `.sdlc/bin/sdlc ci`. Copy both from + (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 @@ -973,6 +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 `.sdlc/bin/sdlc ci`. 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.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/tests/test_manifest.py b/tests/test_manifest.py index 360b48a..d551690 100644 --- a/tests/test_manifest.py +++ b/tests/test_manifest.py @@ -936,13 +936,99 @@ def test_a_launcher_that_is_not_a_bootstrap_release_fails(repo, launcher): assert "is not a python-sdlc bootstrap release" in found -@pytest.mark.parametrize("run", ["bin/sdlc ci", "./tools/sdlc ci", "sdlc ci"]) +@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 "runs `.sdlc/bin/sdlc ci`" in found + 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"]) diff --git a/validate-constitution.py b/validate-constitution.py index 8cea6bb..63eda22 100755 --- a/validate-constitution.py +++ b/validate-constitution.py @@ -360,8 +360,12 @@ 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.""" - found = {} + """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 @@ -370,7 +374,8 @@ def floating_sdlc_hooks(config: dict, launcher: str) -> dict[str, dict]: continue words = str(hook.get("entry", "")).split() if words and words[0].removeprefix("./") == launcher: - found[str(hook.get("id"))] = hook + key = str(hook.get("id")) + found[f"{key}#2" if key in found else key] = hook return found @@ -411,6 +416,11 @@ def check_floating_wiring(repo_root: Path, config: dict, requirements: dict) -> 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-") @@ -430,8 +440,57 @@ def check_floating_wiring(repo_root: Path, config: dict, requirements: dict) -> if stage not in stages: violations.append(f"XII: the `{hook_id}` hook does not run at `{stage}`") violations += check_install_hook_types(config) - if not any(_runs_sdlc_ci(load_yaml(f) or {}, launcher) for f in workflow_files(repo_root)): - violations.append(f"XII: no CI job named `sdlc ci` runs `{launcher} ci`") + 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 @@ -465,15 +524,13 @@ def check_sdlc_wiring(repo_root: Path, hooks: str, requirements: dict) -> list[s return violations -def _runs_sdlc_ci(workflow: dict, launcher: str | None = None) -> bool: +def _runs_sdlc_ci(workflow: dict) -> bool: """A JOB named `sdlc ci` whose steps run the `sdlc ci` command. Parsed, not matched: a regex for `name: sdlc ci` is satisfied by a workflow's or a step's name just as well as a job's, and a job carrying the - right name while running something else would pass it too. With a - `launcher`, the command must be that committed file, not any `sdlc`. + right name while running something else would pass it too. """ - command = rf"(?:\./)?{re.escape(launcher)}" if launcher else r"[\"']?(?:\S*/)?sdlc[\"']?" 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": @@ -483,7 +540,7 @@ def _runs_sdlc_ci(workflow: dict, launcher: str | None = None) -> bool: # The command word of a line must be `sdlc` (by any path), so # `echo sdlc ci` does not count as running it. The command may be # quoted, as a path held in a variable should be. - if re.search(rf"^\s*{command}\s+ci\b", str(run), re.M): + if re.search(r"^\s*[\"']?(?:\S*/)?sdlc[\"']?\s+ci\b", str(run), re.M): return True return False From ea74beeb55b6c16486468d602337bd48ec429d6c Mon Sep 17 00:00:00 2001 From: Josui Date: Tue, 17 Nov 2026 21:24:58 +0000 Subject: [PATCH 4/5] fix(requirements): seed sdlc_bootstrap_sha256 from python-sdlc#62's final bootstrap #62's bin/sdlc-bootstrap is frozen at a483867 (sha256 6c4691c4...). The earlier hash came from an unreleased draft that no repo carries, so it is replaced rather than kept. tests/sdlc-bootstrap is the a483867 file. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN --- profiles/requirements.toml | 2 +- tests/sdlc-bootstrap | 42 +++++++++++++++++++++++++++++--------- 2 files changed, 33 insertions(+), 11 deletions(-) diff --git a/profiles/requirements.toml b/profiles/requirements.toml index 8300923..9143477 100644 --- a/profiles/requirements.toml +++ b/profiles/requirements.toml @@ -41,7 +41,7 @@ sdlc_launcher = ".sdlc/bin/sdlc" # itself. A new bin/sdlc-bootstrap adds its hash here; old ones stay until the # fleet has moved off them. sdlc_bootstrap_sha256 = [ - "87e8649a0724b40e68d2e3f331fb5b3dca5b9b8adb29254f2e88bc9c9c2cd6c1", # python-sdlc#62 + "6c4691c4aea0be66d6a6acd2efdf191a5038a1b3b8396b2fc60d14cd419eca72", # python-sdlc#62 at a483867 ] # Container release (container-image VII, since 1.39.0, RT#1550): repos that diff --git a/tests/sdlc-bootstrap b/tests/sdlc-bootstrap index 6be5056..6fbb342 100755 --- a/tests/sdlc-bootstrap +++ b/tests/sdlc-bootstrap @@ -4,14 +4,16 @@ # 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 any full ref such as a seat's localhost/ -# build. The image prints the launcher with its own ref written into it (`sdlc -# launcher `), so the launcher and the image it starts cannot disagree. +# 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. An `sdlc` RPM would install the same file -# as /usr/bin/sdlc. +# 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 @@ -19,10 +21,29 @@ set -u -image=${SDLC_IMAGE:-latest} -case $image in - */*) ;; - *) image=quay.io/crunchtools/sdlc:$image ;; +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 @@ -37,4 +58,5 @@ if ! podman --events-backend=none run --rm --log-driver=none --network=none \ printf 'sdlc: GATE CANNOT RUN: %s could not print its launcher\n' "$image" >&2 exit 2 fi -sh "$dir/sdlc" "$@" +# The launcher reads SDLC_IMAGE too; it gets the full reference checked here. +SDLC_IMAGE=$image sh "$dir/sdlc" "$@" From a8dc712d94eda17b7d595503ce5384856849907a Mon Sep 17 00:00:00 2001 From: Josui Date: Tue, 17 Nov 2026 21:38:30 +0000 Subject: [PATCH 5/5] chore(gatehouse): mirror gatehouse#150's guard rename comment The guard job now matches crunchtools/gatehouse examples/gatehouse.yml at 4ae89d0 line for line. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN --- .github/workflows/gatehouse.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/gatehouse.yml b/.github/workflows/gatehouse.yml index 032fdf9..ee4a244 100644 --- a/.github/workflows/gatehouse.yml +++ b/.github/workflows/gatehouse.yml @@ -67,7 +67,7 @@ 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|\.sdlc)/'; then