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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/constitution.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ permissions:
jobs:
constitution:
name: Constitution
uses: crunchtools/constitution/.github/workflows/validate.yml@v1.31.0
uses: crunchtools/constitution/.github/workflows/validate.yml@v1.35.0
2 changes: 1 addition & 1 deletion .github/workflows/dependabot-automerge.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,4 @@ permissions:
jobs:
automerge:
name: Dependabot
uses: crunchtools/constitution/.github/workflows/dependabot-automerge.yml@v1.31.0
uses: crunchtools/constitution/.github/workflows/dependabot-automerge.yml@v1.35.0
2 changes: 1 addition & 1 deletion .specify/memory/constitution.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
> **Ratified:** 2026-11-04
> **Amended:** 2026-11-04
> **Status:** Active
> **Inherits:** [crunchtools/constitution](https://github.com/crunchtools/constitution) v1.31.0
> **Inherits:** [crunchtools/constitution](https://github.com/crunchtools/constitution) v1.35.0
> **Profile:** Container Image

This is a manifest. It carries only what is unique to this repo; the fleet rules
Expand Down
29 changes: 27 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,31 @@ All notable changes to this project are documented here, following

## [Unreleased]

### Added

- **Exit 3: could not run, deferred to CI** (constitution 1.35.0, XII). When
CodeQL itself breaks at the push tier, outside CI, in a repo whose workflow
RUNS `bin/sdlc ci`, the push goes through with a loud `DEFERRED TO CI` and the
record shows exit 3. Before this, a broken CodeQL blocked every push and
`--no-verify`, which skips every gate, was the only way past it. `sdlc ci`,
`sdlc codeql` and a config error are still 2. A tool's own exit 3 is mapped to
2, so only the gate can defer, and it is granted per check -- today only
CodeQL. The text `sdlc ci` alone does not unlock it: a comment, a YAML `name:`
and an echoed string are mentions, not runs, and trentina has two of those.
The question is answered from the PARSED workflow: an unconditional
`steps[].run` invoking a path ending in `bin/sdlc` with `ci` as its argument,
in a workflow whose `push`, `pull_request`, `pull_request_target` or
`merge_group` trigger is unfiltered or reaches the default branch under
GitHub's own glob rules. A job name,
a step name, an `env:` value, a comment and an echoed string are mentions;
a job or step behind an `if:` may be skipped on this commit; `on: push`
filtered to another branch judges nothing; a file that does not parse grants
nothing (#33, constitution#99).

### Changed

- Inherits constitution v1.35.0, the release that amended XII to allow exit 3.

### Fixed

- **CodeQL's evaluator gets the memory the gate budgets.** CodeQL ignored the
Expand All @@ -18,8 +43,8 @@ All notable changes to this project are documented here, following
other's database mid-run. The previous database is removed, read-only parts
included, and checked to be gone before `create` runs (#33).
- `run_plan` read run_serial's per-step `_rc` as its own result, because shell
variables are global. Harmless today, because every non-zero step fails the
run, but one new status away from a wrong exit code.
variables are global. It had no visible effect while every non-zero step
failed the run, but it turned a deferred push's 0 into a 3.

## [0.5.3] - 2026-11-08

Expand Down
42 changes: 38 additions & 4 deletions bin/sdlc
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,10 @@
# 0 ran, found nothing
# 1 ran, found something
# 2 COULD NOT RUN -- never to be worked around
# 3 COULD NOT RUN, deferred to CI -- push only, granted by the image when
# CodeQL itself broke and `sdlc ci` will judge the same commit. Printed
# loudly, recorded, and not a refusal (python-sdlc#33). Anywhere but a
# push it is a 2.
#
# Podman's own 125/126/127 mean the container never started, so they map to 2.
# trentina's gates.sh maps them to 1 via `|| fail`, which reports "found
Expand Down Expand Up @@ -271,6 +275,8 @@ run_in_image() {
-e "SDLC_PROJECT=$PROJECT" \
-e "SDLC_JOBS=$GATE_CPUS" \
-e "SDLC_MEMORY=$GATE_MEMORY" \
-e "SDLC_DEFAULT_BRANCH=$(default_branch 2>/dev/null || :)" \
${SDLC_TIER:+-e SDLC_TIER} \
-e "SDLC_HOST_REPO=$REPO" \
-e "SDLC_CACHE_VOLUME=$CACHE_VOLUME" \
${SDLC_SKIP:+-e SDLC_SKIP} \
Expand Down Expand Up @@ -485,6 +491,20 @@ run_host() {
}

run_step() { # mode payload -> the step's exit status
_rs=0
_run_step "$@" || _rs=$?
# Only a push may defer to CI. Anything else that reports 3 could not run.
if [ "$_rs" -eq 3 ] && [ "${SDLC_TIER:-}" != push ]; then return 2; fi
return "$_rs"
}

deferred() { # check -> the warning a deferral prints, every time
printf '\n%s: %s COULD NOT RUN -- DEFERRED TO CI.\n' "$ME" "$1" >&2
printf '%s: This push is not blocked, and nothing was judged here.\n' "$ME" >&2
printf '%s: The "sdlc ci" job is the verdict on this commit.\n' "$ME" >&2
}

_run_step() {
case "$1" in
image-ro) run_in_image ro nostdin "$IMAGE" "$2" ;;
image-rw) run_in_image rw nostdin "$IMAGE" "$2" ;;
Expand Down Expand Up @@ -542,7 +562,11 @@ run_serial() { # the plan -> its worst step status
_rc=0
run_step "$_mode" "$_payload" || _rc=$?
_scur_took=$(( _scur_took + $(now_s) - _t0 ))
if [ "$_rc" -ne 0 ]; then
if [ "$_rc" -eq 3 ]; then
_failed="$_failed $_check"
_scur_rc=3
deferred "$_check"
elif [ "$_rc" -ne 0 ]; then
_failed="$_failed $_check"
_scur_rc=$_rc
printf '\n%s: %s %s after %ss\n' "$ME" "$_check" \
Expand Down Expand Up @@ -607,6 +631,8 @@ _close_check() { # the open check's block is complete
# and then the run -- ended with two, the first of them "passed in 0s".
if [ "$_cur_rc" -eq 0 ]; then
printf '\n== %s passed in %ss\n' "$_cur_name" "$_cur_took" >> "$OUT/out.$_cur"
elif [ "$_cur_rc" -eq 3 ]; then
deferred "$_cur_name" 2>> "$OUT/out.$_cur"
else
printf '\n%s: %s %s after %ss\n' "$ME" "$_cur_name" \
"$([ "$_cur_rc" -eq 2 ] && echo 'COULD NOT RUN' || echo 'FAILED')" \
Expand Down Expand Up @@ -662,7 +688,10 @@ run_lane() { # lane-index steps-file lane-cpus -> the lane's worst
_rc=0
run_step "$_mode" "$_payload" >> "$OUT/out.$_i" 2>&1 || _rc=$?
_cur_took=$(( _cur_took + $(now_s) - _t0 ))
if [ "$_rc" -ne 0 ]; then
if [ "$_rc" -eq 3 ]; then
_failed="$_failed $_check"
_cur_rc=3
elif [ "$_rc" -ne 0 ]; then
_failed="$_failed $_check"
_cur_rc=$_rc
# A later 1 must not mask an earlier 2, in this lane or any other.
Expand Down Expand Up @@ -872,6 +901,9 @@ run_lanes() { # the plan -> the worst status of every lane
}

run_plan() { # commit | push | ci | <check>
# The image asks this to decide whether CodeQL may defer to CI.
SDLC_TIER=$1
export SDLC_TIER
_plan=$(run_in_image ro nostdin "$IMAGE" plan "$1") \
|| die "the image could not plan '$1'; nothing was checked"
[ -n "$_plan" ] || die "the image planned nothing for '$1'"
Expand All @@ -889,8 +921,8 @@ run_plan() { # commit | push | ci | <check>
_oncpu=$(printf '%s\n' "$_plan" \
| awk -F"$TAB" '$3 != "local" && !seen[$2]++ {n++} END {print n + 0}')
# Its own name: shell variables are global, and run_serial's loop sets `_rc`
# for every step, so the last step's status leaked in here whenever
# run_serial itself returned 0.
# for every step. A deferred step's 3 survived into here and became the
# exit status of a push that run_serial had passed.
_plan_rc=0
if [ "${_n:-1}" -le 1 ]; then
run_serial "$_plan" || _plan_rc=$?
Expand Down Expand Up @@ -931,6 +963,8 @@ usage: $ME commit | push | ci | <check> | tiers | list | versions | codeql-basel
Configure each command in pyproject.toml: [tool.sdlc.commit],
[tool.sdlc.push], [tool.sdlc.ci]. Skip one check once: SDLC_SKIP=name.
Exit 2 means a check COULD NOT RUN and is never to be worked around.
A push prints DEFERRED TO CI, and goes through, only when CodeQL itself broke
and the repo's \`sdlc ci\` job will judge the same commit.

Working a change, in the order that costs least:

Expand Down
36 changes: 35 additions & 1 deletion docs/codeql.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ fails.

## When it cannot run

Two things went wrong on josui-skills at once (#33).
Three things went wrong on josui-skills at once (#33), and each has its own fix.

- **Memory.** CodeQL sizes its evaluator itself and does not look at the
container: `codeql resolve ram` gave a 1509 MB heap under `--memory 8g` and
Expand All @@ -49,6 +49,40 @@ Two things went wrong on josui-skills at once (#33).
database mid-run. The gate now takes a lock beside it and waits. It clears
the previous database before building and checks that it is gone. A
half-built one is a cache miss, not something a person deletes by hand.
- **Deferring to CI.** When CodeQL itself breaks — `create` or `analyze` exits
non-zero — at the **push** tier, outside CI, in a repo whose CI really runs
the gate, the check exits **3**. The launcher prints `DEFERRED TO CI`,
records it in `last-push.json`, and lets the push through. Anywhere else (`sdlc ci`,
`sdlc codeql`, a repo with no such workflow) it is still a 2. A config the
repo got wrong is still a 2 everywhere, because CI fails on it the same way.
Constitution XII, v1.35.0, is what permits this; nothing else may defer.

"Really runs the gate" is answered from the parsed workflow, never by
searching it as text, because every loose answer hands a push a verdict nobody
reaches:

- an **unconditional `steps[].run`** that invokes a path ending in `bin/sdlc`
with `ci` as its argument. A job name, a step name, an `env:` value, a
comment and an echoed string are mentions — trentina carries two of them.
A job or step behind an `if:` may be skipped on this very commit, so it
grants nothing: ashigaru's `sdlc ci` job sits behind `ASHIGARU_ENABLED`, and
a broken CodeQL there is correctly still a 2.
- a **trigger that reaches the commit**: `push`, `pull_request`,
`pull_request_target` or `merge_group`, unfiltered or naming the default
branch — the branch XII's required status check guards, matched with
GitHub's own glob rules, where `*` stops at a `/` and `**` does not.
`workflow_dispatch` alone judges nothing anybody pushed, and `on: push`
filtered to another branch is the same gap wearing the right event name.
Two filters are not evaluated at all and grant nothing: `branches-ignore`,
which needs every branch name to judge, and any `branches` list carrying a
negation, because GitHub applies those in order and `['**', '!main']`
excludes `main` while matching everything.

A workflow this cannot parse grants nothing, and neither does a run where the
default branch is unknown and the trigger is filtered.

`--no-verify` skips every gate, so refusing the push left it as the only way
past one broken tool. A deferral leaves the other gates running.

## The config file

Expand Down
Loading
Loading