Skip to content

feat: jq in the image, and a stated boundary for the shell test toolbox - #13

Merged
fatherlinux merged 3 commits into
mainfrom
feature/1552-jq-in-toolbox
Nov 4, 2026
Merged

fatherlinux merged 3 commits into
mainfrom
feature/1552-jq-in-toolbox

Conversation

@fatherlinux

Copy link
Copy Markdown
Member

Two repos in the fleet conversion failed sdlc ci on pytest for the same
reason, and it was not their code: jq: command not found.

  • crunchtools/josui: all four entrypoint tests. The entrypoint is a shell
    script and calls jq at line 87.
  • crunchtools/claude-agent: 4 of 103 shell-hook tests. mypy, pip-audit, the
    constitution validator and CodeQL all pass there; the only external command
    the hook calls is jq.

This is not one repo's quirk. Claude Code hands a hook its event as JSON on
stdin, hooks are shell scripts, and jq is the smallest correct way to read JSON
from bash. Both repos declare Requires: jq in their own package manifests
(packaging/claude-agent.spec:16 and the debian control file; josui's
Containerfile installs it). More hook-shipping repos are coming.

The alternative was to run those tests inside each repo's own built image with
the pytest-in-image kind. That is the right answer for a per-repo runtime
dependency, and it is the answer for crunchtools/tig, whose tests need the
image's install paths (crunchtools/tig#29). It is the wrong answer here:
claude-agent's reference Containerfile installs the PUBLISHED package, so
building it in the gate would test the last release rather than the pull
request. Its real install test is already the 8-distro matrix in packages.yml.
Those four are unit tests of a shipped script whose declared dependency is jq,
and unit tests belong in the gate image.

So jq goes in, and the boundary goes in as a comment above the dnf install,
where someone adding the next package will read it: beyond the checks this
image carries bash, coreutils, git, curl, python3 and jq, and nothing else. A
test that reaches for socat, nc, node or a repo's own runtime is an integration
test and belongs in pytest-in-image against that repo's image, or in a new
kind. Without a written line this list becomes a host-tools grab bag one repo
at a time.

tests/contract.sh now asserts jq, curl and bash execute, alongside the checks it
already proves. That makes the toolbox a tested property of the image rather
than an accident of the base, which matters because the base is Hummingbird and
deliberately thin -- which is already in this list for exactly that reason.

RT#1552

🤖 Generated with Claude Code

https://claude.ai/code/session_01R7Y1jesjfgxHeqtKJCvay6

Two repos in the fleet conversion failed `sdlc ci` on pytest for the same
reason, and it was not their code: `jq: command not found`.

- crunchtools/josui: all four entrypoint tests. The entrypoint is a shell
  script and calls jq at line 87.
- crunchtools/claude-agent: 4 of 103 shell-hook tests. mypy, pip-audit, the
  constitution validator and CodeQL all pass there; the only external command
  the hook calls is jq.

This is not one repo's quirk. Claude Code hands a hook its event as JSON on
stdin, hooks are shell scripts, and jq is the smallest correct way to read JSON
from bash. Both repos declare `Requires: jq` in their own package manifests
(packaging/claude-agent.spec:16 and the debian control file; josui's
Containerfile installs it). More hook-shipping repos are coming.

The alternative was to run those tests inside each repo's own built image with
the `pytest-in-image` kind. That is the right answer for a per-repo runtime
dependency, and it is the answer for crunchtools/tig, whose tests need the
image's install paths (crunchtools/tig#29). It is the wrong answer here:
claude-agent's reference Containerfile installs the PUBLISHED package, so
building it in the gate would test the last release rather than the pull
request. Its real install test is already the 8-distro matrix in packages.yml.
Those four are unit tests of a shipped script whose declared dependency is jq,
and unit tests belong in the gate image.

So jq goes in, and the boundary goes in as a comment above the `dnf install`,
where someone adding the next package will read it: beyond the checks this
image carries bash, coreutils, git, curl, python3 and jq, and nothing else. A
test that reaches for socat, nc, node or a repo's own runtime is an integration
test and belongs in `pytest-in-image` against that repo's image, or in a new
kind. Without a written line this list becomes a host-tools grab bag one repo
at a time.

tests/contract.sh now asserts jq, curl and bash execute, alongside the checks it
already proves. That makes the toolbox a tested property of the image rather
than an accident of the base, which matters because the base is Hummingbird and
deliberately thin -- `which` is already in this list for exactly that reason.

RT#1552

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

@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)

Full review.

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

1 finding(s) not raised: already judged in gatehouse-findings.toml on this branch.

Comment thread gatehouse-findings.toml
agent = "constitution"
category = "constitution"
file = "Containerfile"
evidence = "RUN dnf install -y git-core tar zstd which jq \\"

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 (Ledger): This branch silences a constitution finding in Containerfile as not-a-bug: Same reasoning as the base-image finding above, and the same four unpinned neighbours: git-core, tar, zstd and which have never carried exact RPM versions on this line. The Container Image profile requires a weekly rebuild (0 6 * * 1) whose entire purpose is to pick up OS security updates; pinning an OS package to an exact version is how you build an image that stops receiving them, which is the opposite of what the cron is for. What the constitution pins to exact versions is the CHECK tools -- ruff, mypy, semgrep, pip-audit, CodeQL, Gourmand, Gatehouse -- because a verdict that changes under you is not a verdict; those are pinned by ARG and reported by sdlc versions. jq is not a check, it is part of the shell test toolbox, and its filter language is stable across every version the fleet ships. Pinning it would freeze a CVE-bearing RPM into the gate image for no gain in reproducibility that the digest-addressed release does not already provide.

Suggestion: Confirm the judgement is right, or drop the entry and fix the finding. The entry stops applying on its own once the code it quotes is gone.

Evidence:

RUN dnf install -y git-core tar zstd which jq \

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: the ledger is right to stop on it, and here is the reasoning for the record.

The silenced finding asks for jq to be pinned to an exact RPM version. Three things say otherwise:

  1. Its four neighbours are unpinned too. git-core, tar, zstd and which have never carried exact versions on that line. jq is consistent with them, not an exception to a rule being followed.
  2. The Container Image profile mandates a weekly rebuild (0 6 * * 1) whose entire purpose is to pick up base-image errata. Pinning an OS package to an exact version is how an image stops receiving them — the opposite of what that cron exists for. The same reasoning is already recorded in this file for the base image itself, a few entries up.
  3. What the constitution pins to exact versions is the CHECK tools — ruff, mypy, semgrep, pip-audit, CodeQL, Gourmand, Gatehouse — because a verdict that changes underneath you is not a verdict. Those are pinned by ARG and reported by sdlc versions. jq is not a check; it is part of the shell test toolbox, and its filter language is stable across every version the fleet ships.

Reproducibility is not lost either: consumers pin this image by exact release (rev: v0.3.6), and promote copies a digest rather than rebuilding, so what a repo gets is a fixed set of bytes regardless of which jq build went into it.

The one thing that would change my mind is jq becoming load-bearing for a verdict rather than for a test fixture. It is not, and the comment above the dnf install now says where that line is.

`container.yml`'s concurrency group was keyed on `github.run_id`. That value is
unique per run, so every run sat in a group of its own and the group controlled
nothing at all.

A merge to main and the tag `release.yml` creates from it are two pushes of the
SAME commit. Both built it, both pushed the same `:<sha>` tag, the second
replaced the first's manifest, and then the loser's "Verify the pushed digest"
step failed with `manifest unknown` on a digest that no longer existed.

v0.3.4 happened to win that race. v0.3.5 lost it: the main run moved `latest`,
the tag run failed, and the `0.3.5` tag was never created. There is a git tag
and a GitHub release for v0.3.5 with no image behind them, which is the one
state a fleet pinning this image by exact release cannot survive -- `sdlc`
exits 2 with "manifest unknown" and nothing is checked. The only reason no repo
is broken by it is that the promote job which opens the version-bump pull
requests lives in the run that failed, so the bump never went out.

Keyed on `github.sha`, the two runs serialize and the second verifies the digest
it just pushed. `cancel-in-progress` stays false off pull requests: cancelling
the main run when its tag arrives would abandon a push half-finished.

v0.3.5 is superseded by this release rather than backfilled.

RT#1552

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

@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 2 issues (2 medium)

Reviewed 1 commit since dd52d6d (incremental).

# when its tag arrives would abandon a push half-done.
concurrency:
group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}

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 (Bug Hunter): GitHub Actions keeps at most one pending run per concurrency group; when another run enters the same group, it cancels and replaces the existing pending run, even with cancel-in-progress: false. If the main build is running and the tag build is pending, a workflow_dispatch or scheduled run for the same SHA can replace the tag build, leaving the release tag without its image.

Suggestion: Ensure required tag builds cannot be displaced by other runs in the same group—for example, consolidate the main and tag handling into one run or use a queuing design that preserves every required run.

Evidence:

group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.sha }}

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 for the path this fixes, and you are right about the limit. Worth being precise about both.

You are correct that a concurrency group holds at most one PENDING run and a third entrant cancels the one waiting. The release path has exactly two: the push to main, and the tag release.yml creates from that same commit. Two runs, so one runs and one pends, and nothing is cancelled. A third run on the SAME sha would have to be a manual re-run or a schedule firing on a head that has not moved — and today that third run does not queue, it races, which is how v0.3.5 lost its image. Serialized-and-possibly-cancelled is a better failure than concurrent-and-silently-overwritten.

On the end state, which matters more: promote already has its own fixed group (promote-python-sdlc, never cancelled) and a backwards-move guard, so promotions cannot interleave. Serialized, the main run builds and promotes, then the tag run builds, verifies ITS digest, and promotes that one — so latest, :0.3.6 and :<sha> all end at the second build. Consistent, with one orphaned digest from the first build as the cost.

What this does NOT fix, and what you have really put your finger on: the same commit is built twice at all. The workflow's own header says the design is "the build pushes ONLY the commit SHA tag... latest plus the semver tags move in a separate promote job that copies that tested digest without rebuilding" — and a tag event should therefore promote the :<sha> image that already exists rather than rebuild it. That removes the second build, the orphaned digest and the pending-run question in one go. It is a restructure of build/promote wiring rather than a one-line group change, so I am not folding it into a pull request whose subject is jq; filing it as the follow-up.

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: the two-run release path cannot hit the pending-run cancellation, and the end state is consistent.

Restating in the form the triage check accepts — my earlier reply on this thread opened "not a bug for the path this fixes", without the colon, so it did not count as an answer. Same content.

You are right that a concurrency group holds at most one PENDING run and a third entrant cancels the one waiting. The release path has exactly two runs: the push to main, and the tag release.yml creates from that same commit. One runs, one pends, nothing is cancelled. A third run on the same sha would need a manual re-run or a schedule firing on an unmoved head — and today that third run does not queue at all, it races, which is how v0.3.5 lost its image.

On the end state, which matters more than the queue: promote already has its own fixed group (promote-python-sdlc, never cancelled) and a backwards-move guard, so promotions cannot interleave. Serialized, the main run builds and promotes, then the tag run builds, verifies its own digest and promotes that — so latest, 0.3.6 and the sha tag all land on the second build. One orphaned digest from the first build is the cost.

What this does not fix is the real thing you found: the same commit is built twice at all. The workflow header already says a tag should promote the digest the main run built rather than rebuild it, and doing that removes the second build, the orphan and this question together. It is a restructure of the build/promote wiring, not a one-line group change, so it is #14 rather than this pull request, whose subject is jq.

Comment thread gatehouse-findings.toml
agent = "constitution"
category = "constitution"
file = "Containerfile"
evidence = "RUN dnf install -y git-core tar zstd which jq \\"

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 (Ledger): This branch silences a constitution finding in Containerfile as not-a-bug: Same reasoning as the base-image finding above, and the same four unpinned neighbours: git-core, tar, zstd and which have never carried exact RPM versions on this line. The Container Image profile requires a weekly rebuild (0 6 * * 1) whose entire purpose is to pick up OS security updates; pinning an OS package to an exact version is how you build an image that stops receiving them, which is the opposite of what the cron is for. What the constitution pins to exact versions is the CHECK tools -- ruff, mypy, semgrep, pip-audit, CodeQL, Gourmand, Gatehouse -- because a verdict that changes under you is not a verdict; those are pinned by ARG and reported by sdlc versions. jq is not a check, it is part of the shell test toolbox, and its filter language is stable across every version the fleet ships. Pinning it would freeze a CVE-bearing RPM into the gate image for no gain in reproducibility that the digest-addressed release does not already provide.

Suggestion: Confirm the judgement is right, or drop the entry and fix the finding. The entry stops applying on its own once the code it quotes is gone.

Evidence:

RUN dnf install -y git-core tar zstd which jq \

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: the ledger is right to stop on it, and here is the reasoning for the record.

The silenced finding asks for jq to be pinned to an exact RPM version. Three things say otherwise:

  1. Its four neighbours are unpinned too. git-core, tar, zstd and which have never carried exact versions on that line. jq is consistent with them, not an exception to a rule being followed.
  2. The Container Image profile mandates a weekly rebuild (0 6 * * 1) whose entire purpose is to pick up base-image errata. Pinning an OS package to an exact version is how an image stops receiving them — the opposite of what that cron exists for. The same reasoning is already recorded in this file for the base image itself, a few entries up.
  3. What the constitution pins to exact versions is the CHECK tools — ruff, mypy, semgrep, pip-audit, CodeQL, Gourmand, Gatehouse — because a verdict that changes underneath you is not a verdict. Those are pinned by ARG and reported by sdlc versions. jq is not a check; it is part of the shell test toolbox, and its filter language is stable across every version the fleet ships.

Reproducibility is not lost either: consumers pin this image by exact release (rev: v0.3.6), and promote copies a digest rather than rebuilding, so what a repo gets is a fixed set of bytes regardless of which jq build went into it.

The one thing that would change my mind is jq becoming load-bearing for a verdict rather than for a test fixture. It is not, and the comment above the dnf install now says where that line is.

Constitution II: every file that states the version states the same one. I
moved IMAGE_TAG and pyproject.toml to 0.3.6 and left `LABEL version="0.3.5"`
behind, and `Constitution / Validate constitution` said so:

    VERSION: Containerfile says 0.3.5, CHANGELOG.md says 0.3.6 (II)

Which is the check working. mcp-github's 2.0.0 was bumped by hand in two of its
five places and could not be tagged; that is why the rule exists.

RT#1552

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

@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 232946f (incremental).

Comment thread gatehouse-findings.toml
agent = "constitution"
category = "constitution"
file = "Containerfile"
evidence = "RUN dnf install -y git-core tar zstd which jq \\"

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 (Ledger): This branch silences a constitution finding in Containerfile as not-a-bug: Same reasoning as the base-image finding above, and the same four unpinned neighbours: git-core, tar, zstd and which have never carried exact RPM versions on this line. The Container Image profile requires a weekly rebuild (0 6 * * 1) whose entire purpose is to pick up OS security updates; pinning an OS package to an exact version is how you build an image that stops receiving them, which is the opposite of what the cron is for. What the constitution pins to exact versions is the CHECK tools -- ruff, mypy, semgrep, pip-audit, CodeQL, Gourmand, Gatehouse -- because a verdict that changes under you is not a verdict; those are pinned by ARG and reported by sdlc versions. jq is not a check, it is part of the shell test toolbox, and its filter language is stable across every version the fleet ships. Pinning it would freeze a CVE-bearing RPM into the gate image for no gain in reproducibility that the digest-addressed release does not already provide.

Suggestion: Confirm the judgement is right, or drop the entry and fix the finding. The entry stops applying on its own once the code it quotes is gone.

Evidence:

RUN dnf install -y git-core tar zstd which jq \

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: the ledger is right to stop on it, and here is the reasoning for the record.

The silenced finding asks for jq to be pinned to an exact RPM version. Three things say otherwise:

  1. Its four neighbours are unpinned too. git-core, tar, zstd and which have never carried exact versions on that line. jq is consistent with them, not an exception to a rule being followed.
  2. The Container Image profile mandates a weekly rebuild (0 6 * * 1) whose entire purpose is to pick up base-image errata. Pinning an OS package to an exact version is how an image stops receiving them — the opposite of what that cron exists for. The same reasoning is already recorded in this file for the base image itself, a few entries up.
  3. What the constitution pins to exact versions is the CHECK tools — ruff, mypy, semgrep, pip-audit, CodeQL, Gourmand, Gatehouse — because a verdict that changes underneath you is not a verdict. Those are pinned by ARG and reported by sdlc versions. jq is not a check; it is part of the shell test toolbox, and its filter language is stable across every version the fleet ships.

Reproducibility is not lost either: consumers pin this image by exact release (rev: v0.3.6), and promote copies a digest rather than rebuilding, so what a repo gets is a fixed set of bytes regardless of which jq build went into it.

The one thing that would change my mind is jq becoming load-bearing for a verdict rather than for a test fixture. It is not, and the comment above the dnf install now says where that line is.

@fatherlinux
fatherlinux merged commit 39bcfce into main Nov 4, 2026
39 of 49 checks passed
@fatherlinux
fatherlinux deleted the feature/1552-jq-in-toolbox branch November 4, 2026 22:57
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