Skip to content

feat: accept the floating sdlc launcher in XII; constitution 1.46.0 - #157

Merged
fatherlinux merged 5 commits into
mainfrom
feat/floating-sdlc-launcher
Nov 17, 2026
Merged

fatherlinux merged 5 commits into
mainfrom
feat/floating-sdlc-launcher

Conversation

@fatherlinux

@fatherlinux fatherlinux commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

What

XII now prefers the floating sdlc launcher from crunchtools/python-sdlc#62 as the wiring for every repo kind. The launcher is a committed .sdlc/bin/sdlc. Two repo: local, language: system hooks run it as entry: .sdlc/bin/sdlc commit and entry: .sdlc/bin/sdlc push, with no rev:. The sdlc ci job runs .sdlc/bin/sdlc ci.

  • Validator. check_floating_wiring applies to any repo whose hooks run the launcher, and judges it by that form alone. It requires:
    • the launcher is a committed, executable regular file, not a symlink, and its sha256 is listed in sdlc_bootstrap_sha256
    • both hooks are language: system with the right entry, with no duplicate ids
    • the push hook runs at pre-push
    • default_install_hook_types names both stages
  • The sdlc ci job (check_floating_ci). This job is the required check, so nothing may turn it green without judging:
    • the step's run is exactly .sdlc/bin/sdlc ci, so no || true, no second line and no other script
    • neither the job nor the step has an if: that could be false, or continue-on-error
    • SDLC_IMAGE is unset or exactly ${{ vars.SDLC_IMAGE }} at workflow, job and step env:, because a PR must not choose its judge
  • Why the hash pin. Without it, a repo could commit a script that exits 0 and pass its own hooks and its required check. The image still floats; only the file the gate trusts is pinned. sdlc_bootstrap_sha256 is a list: a bootstrap change adds a hash and there is no flag day.
  • Seeded hash. The list is seeded from feat: v1.26.0 agents reach a forge only through the gateway #62's current bin/sdlc-bootstrap (87e8649a…). It will be re-seeded from the final bytes once feat: v1.26.0 agents reach a forge only through the gateway #62 merges.
  • Guard. This repo's Protect workflows rejects fork changes under .sdlc/ as well as .github/workflows/. The fleet's copy comes from crunchtools/gatehouse examples/gatehouse.yml, which needs the same change.
  • Still accepted until the wave finishes: the rev-pinned python-sdlc hook, and the standalone Gourmand/Gatehouse hooks. Their checks are unchanged.
  • No version gate. Accepting a form is not a new requirement, so it applies at any Inherits.
  • requirements.toml gets sdlc_launcher and sdlc_bootstrap_sha256. sdlc joins floating_images.
  • Release 1.46.0. The brief asked for 1.43.0, but 1.43.0 through 1.45.0 already exist. This PR bumps the version, moves the refs, rolls the CHANGELOG and adds the history row, as release: constitution 1.45.0 #152 did. After merge, cut v1.46.0 at the merge sha and dispatch major-tag.yml.

Known residual, accepted

The rev-pinned and standalone forms have always been matched by text. They still accept a fake repo: local script, || true, if: false and continue-on-error. Left as is: both forms stop being accepted once the conversion wave finishes, and v2 drops them.

Pilots

Each pilot was converted with #62's scripts/convert_repo.py --apply at the commit #62 records.

pilot @ commit before after
josui @ 97514e8 FAIL: must pin python-sdlc PASS
mcp-nagios @ 1b31d75 FAIL: must pin python-sdlc PASS (6 report-only PINS warnings)
syslog @ 017b592 FAIL: no gourmand / gatehouse hook PASS
syslog with an exit 0 launcher n/a FAIL: not a python-sdlc bootstrap release

Tests

The full suite passes (364). The tests cover every case from the a213 review, using the real bootstrap vendored as tests/sdlc-bootstrap. sdlc commit and sdlc push pass locally.

Not merged: ready for review. v2/ and docs/constitution-v2 (#156) are untouched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Gatehouse found no issues.

Full review.

4 finding(s) dropped: their evidence is not in the diff.

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN
@fatherlinux

Copy link
Copy Markdown
Member Author

Review (a213, Dolza 1 - Max) at 2603041. Tests pass (339). 2 blocking findings, then nits.

How I tested: I converted a scratch copy of josui main with python-sdlc#62's own scripts/convert_repo.py --apply (at 3947763), committed the result, then ran this PR's validate-constitution.py against it with one change at a time:

# Change to the converted repo Validator
1 none (honest conversion) PASS
2 .sdlc/bin/sdlc replaced with #!/bin/sh + exit 0 PASS
3 CI step run: ./tools/x/sdlc ci || true (another script) PASS
4 CI step SDLC_IMAGE: ghcr.io/attacker/sdlc:evil PASS
5 if: false on the sdlc ci job PASS
6 continue-on-error: true on the step PASS

Blocking

B1. Nothing checks what the launcher contains, and nothing guards the file. check_floating_wiring checks only that .sdlc/bin/sdlc is a regular, executable file. Case 2 passes, and so does this PR's own fixture (float_repo writes #!/bin/sh\n).

  • On pull_request, CI runs the PR's copy of that file. The local hooks run the committed copy too.
  • So a PR that edits .sdlc/bin/sdlc turns the required sdlc ci check green with no checks run.
  • A fork PR can do it as well: Protect workflows only rejects changes under .github/workflows/.
  • The forms this replaces executed code pinned elsewhere: a rev-pinned repo, a named image, or a workflow file the guard protects. The floating form moves the thing that runs into an ordinary, unguarded repo file.

Fix:

  • Pin the bootstrap's bytes in requirements.toml, as sdlc_launcher_sha256 (a list, so it can rotate). The bootstrap "never names a release", so its hash is stable.
  • Have check_floating_wiring compare it. Constitution / Validate constitution is a required check and runs the validator from @v1, not from the PR, so that comparison holds against a PR.
  • Add a negative test: a modified launcher must fail.
  • Defence in depth: extend the Protect workflows path match to ^\.sdlc/.
  • Ordering: the bootstrap lives in python-sdlc#62, which hasn't merged, so take the hash from feat: v1.26.0 agents reach a forge only through the gateway #62's final bytes.

B2. Nothing makes the image come from the variable. python-sdlc's examples/ci.yml says the image comes from vars.SDLC_IMAGE ("a variable, which only an admin sets, rather than a line a pull request could change"). The validator doesn't enforce that, and the bootstrap accepts any */* ref (case 4). In the floating form, _runs_sdlc_ci should require two things on the sdlc ci step:

  • the run line is exactly .sdlc/bin/sdlc ci;
  • SDLC_IMAGE is either absent or exactly ${{ vars.SDLC_IMAGE }}.

Not blocking, but worth fixing in the same pass

  • Cases 3, 5 and 6 predate this PR. The _runs_sdlc_ci regex accepts any path ending in /sdlc, a trailing || true, a job with if: false and a step with continue-on-error: true. The rev-pinned path has the same holes. For the floating form, reject if: and continue-on-error on the job and the step.

Question 2: does "judged by this form alone" drop a check that still matters?

No. The new branch replaces only check_sdlc_wiring and check_standalone_hooks. These all still run:

  • the Gatehouse triage check, which sits after the if/elif;
  • the Gourmand CI gate and gate-workflow checks (check_gate_workflows);
  • the host contract;
  • the Protect-workflows guard check.

What does move is trust. A non-Python repo used to get Gourmand and Gatehouse at commit from named images; now it gets them from whatever the launcher runs. That is why B1 matters.

Nits

  • floating_sdlc_hooks keys hooks by id, so a second hook with the same id silently replaces the first. Flag duplicates instead.
  • The check_install_hook_types refactor (parsed, not matched) is a good change.

Release shape

  • The version strings and the dated [1.46.0] CHANGELOG section are in this PR, so the merge commit is the release.
  • Cut v1.46.0 at the merge sha promptly. validate.yml, dependency-audit.yml and container-release.yml now reference a v1.46.0 that doesn't exist yet. That's the same shape release: constitution 1.45.0 #152 used for 1.45.0.
  • Then dispatch major-tag.yml, since a release published with GITHUB_TOKEN starts no workflow, so @v1 moves.
  • Order: python-sdlc#62 (and its sdlc image) should land before the pilots convert. With B1, it should also land before this PR, so the hash pin matches the final bytes.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Gatehouse found 1 issues (1 medium)

Reviewed 1 commit since 2603041 (incremental).

5 finding(s) dropped: their evidence is not in the diff.

Comment thread tests/sdlc-bootstrap

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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

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

Evidence:

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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

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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN
@fatherlinux

Copy link
Copy Markdown
Member Author

Re: review a213 (#157 (comment))

B1: Fixed in 371e59d. The launcher must hash to an entry in sdlc_bootstrap_sha256, which is a list so the hash can rotate. The fixture is now the real bootstrap, and a modified launcher fails. Guarding .sdlc/ in Protect workflows is fixed in db3384c, for this repo's copy. The fleet's copy comes from crunchtools/gatehouse examples/gatehouse.yml and needs the same one-line change there. The hash is re-seeded from #62's final bytes once #62 merges.

B2: Fixed in db3384c. In the floating form, SDLC_IMAGE must be unset or exactly ${{ vars.SDLC_IMAGE }} at workflow, job and step env:. The sdlc ci step's run must be exactly .sdlc/bin/sdlc ci.

Cases 3, 5, 6: Fixed in db3384c for the floating form. It rejects || true, a second run line, another script, any if: that is not literally true, and continue-on-error on the job or the step. The rev-pinned path is deliberately unchanged, because those forms stop being accepted after the wave and v2 drops them (PR body, "Known residual").

Nit, duplicate hook ids: Fixed in db3384c. A second hook with the same id is now named instead of silently replacing the first.

Your six cases are now tests: 364 pass, and the three converted pilots still pass.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Gatehouse found no issues.

Reviewed 1 commit since 371e59d (incremental).

7 finding(s) dropped: their evidence is not in the diff.

…inal 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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Gatehouse found 1 issues (1 medium)

Reviewed 1 commit since db3384c (incremental).

1 finding(s) dropped: their evidence is not in the diff.

Comment thread tests/sdlc-bootstrap

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

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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

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

Evidence:

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

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

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

The guard job now matches crunchtools/gatehouse examples/gatehouse.yml at
4ae89d0 line for line.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R7Y1jeqWyD1kaUDpcBw3TN

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Gatehouse found no issues.

Reviewed 1 commit since ea74bee (incremental).

@fatherlinux
fatherlinux merged commit bf7edf9 into main Nov 17, 2026
15 checks passed
@fatherlinux
fatherlinux deleted the feat/floating-sdlc-launcher branch November 17, 2026 21:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant