fix: pin desktop Dockerfile by digest (Scorecard #309) + document publish gap

[Aureliolo]

Summary

• Pin docker/desktop/Dockerfile base image (debian:trixie-slim) and the # syntax= directive by SHA-256 digest, clearing OSSF Scorecard code-scanning alert update repo name #309 (Pinned-Dependencies). The debian digest was verified against the live registry; the syntax digest matches the one already used by every other Dockerfile in the repo.
• Document the desktop image in docs/design/deployment.md as a not-yet-published runtime image (it is referenced by the desktop tool's desktop_image_pin default but never built/signed by CI), and generalise the docs/security.md Renovate-scope sentence (the dockerfile manager + docker:pinDigests already covers every Dockerfile, so the old "backend and sandbox" enumeration was incomplete).
• File Build, publish, and sign the desktop image (referenced by #2031, never wired into CI) #2033 to track the genuine gap surfaced during review: the desktop image (ghcr.io/aureliolo/synthorg-desktop) is referenced by code shipped in feat: virtual desktop tool and vision verifier gate #2031 but is never built, published, or cosign-signed by CI (GHCR returns 404). The deployment doc points at Build, publish, and sign the desktop image (referenced by #2031, never wired into CI) #2033.

Test plan

• Docs + Dockerfile-only change; no runtime code touched.
• Pre-commit (ruff/ruff-format, em-dash gate, hadolint) and pre-push (mypy-affected, pytest-unit-affected, all convention gates, hadolint) passed locally. hadolint validates the pinned Dockerfile.
• Scorecard alert update repo name #309 should clear once this lands on main and the next code-scanning run completes.

Review coverage

Pre-reviewed by 3 agents (infra-reviewer, docs-consistency, comment-quality-rot). infra-reviewer and comment-quality-rot: 0 findings. docs-consistency surfaced the desktop-image documentation gap, addressed here (and the deeper publish gap tracked in #2033).

Resolves Scorecard alert #309. Does not close #2033 (followup tracking the missing build/publish wiring).

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses security compliance by pinning dependencies in the desktop Dockerfile to specific digests. It also improves project documentation to accurately reflect the current state of the desktop image, which is currently defined but not yet integrated into the automated build and publication pipeline.

Highlights

• Security Hardening: Pinned the desktop Dockerfile base image and syntax directive by SHA-256 digest to resolve OSSF Scorecard alert update repo name #309.
• Documentation Updates: Added documentation for the desktop image in deployment.md and clarified the scope of Renovate's automated digest updates in security.md.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 73608cdc-bacc-41dc-adb9-426ee344f029

📥 Commits

Reviewing files that changed from the base of the PR and between 2fa2e1e and 4ec3878.

📒 Files selected for processing (3)

• docker/desktop/Dockerfile
• docs/design/deployment.md
• docs/security.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: Build Web Assets (melange)
• GitHub Check: Lighthouse Site
• GitHub Check: Build Preview
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (go)
• GitHub Check: Analyze (actions)
• GitHub Check: Analyze (python)

🧰 Additional context used

📓 Path-based instructions (2)

{README.md,docs/**/*.md}

📄 CodeRabbit inference engine (CLAUDE.md)

Numeric claims in README and public docs sourced from data/runtime_stats.yaml via <!--RS:NAME--> markers. See data/README.md.

Files:

• docs/design/deployment.md
• docs/security.md

docs/**/*.{md,d2,mmd}

📄 CodeRabbit inference engine (CLAUDE.md)

Use d2 for architecture / nested containers; use mermaid for flowcharts / sequence / pipelines. Use Markdown tables for tabular data. D2 theme 200 (Dark Mauve), D2 CLI pinned to v0.7.1 in CI.

Files:

• docs/design/deployment.md
• docs/security.md

🧠 Learnings (4)

📚 Learning: 2026-05-16T18:36:31.446Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/reference/conventions.md:787-789
Timestamp: 2026-05-16T18:36:31.446Z
Learning: In Aureliolo/synthorg, do not require adding `<!--RS:...-->` “Doc Numeric Claims (MANDATORY)” numeric macros for Python version numbers mentioned in documentation prose (e.g., “Python 3.14”, “Python 3.15”). The `scripts/check_doc_numeric_macros.py` gate only applies to `README.md`, `docs/index.md`, `docs/roadmap/index.md`, `docs/architecture/decisions.md`, and `docs/reference/convention-gates.md`, and it only flags digits adjacent to specific stat nouns (tests/providers/agents/stars/releases), not language version mentions like “Python 3.14”.

Applied to files:

• docs/design/deployment.md
• docs/security.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: When reviewing Markdown in the synthorg repo, account for the CI gate `check_doc_numeric_macros.py`: it skips fenced code blocks entirely, and it only flags digits that are adjacent to these stat nouns: `tests`, `providers`, `agents`, `stars`, `releases`. Therefore, numeric examples such as CLI flag values (e.g., `--num-workers=4` in fenced bash blocks) and prose version numbers (e.g., `3.14`/`3.15`) are not expected to trigger this check; prioritize changes only when digits appear next to one of the listed nouns (e.g., “5 tests”, “10 stars”, etc.).

Applied to files:

• docs/design/deployment.md
• docs/security.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: When reviewing markdown files for the "Doc Numeric Claims (MANDATORY)" RS-marker rule, only require/flag missing RS markers in the files that are actually in-scope for the rule. The scope is enforced via an identical _SCOPED_FILES allowlist in scripts/check_doc_numeric_macros.py and scripts/inject_runtime_stats.py, and currently includes: README.md; docs/index.md; docs/roadmap/index.md; docs/architecture/decisions.md; docs/reference/convention-gates.md. For any other markdown files (e.g., docs/getting_started.md, docs/guides/*), missing RS markers for numeric claims are no-ops and should NOT be flagged.

Applied to files:

• docs/design/deployment.md
• docs/security.md

📚 Learning: 2026-05-16T18:36:35.250Z

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1944
File: docs/getting_started.md:109-109
Timestamp: 2026-05-16T18:36:35.250Z
Learning: When reviewing Markdown in the synthorg repo against the `check_doc_numeric_macros.py` gate, account for its documented behavior: it skips fenced code blocks entirely, and it only flags digits that are adjacent to specific stat nouns (`tests`, `providers`, `agents`, `stars`, `releases`). As a result, CLI-style numbers (e.g., `--num-workers=4`) inside fenced bash code blocks should never be treated as violations of this gate; only non-fenced text needs checking, and only around those specific nouns.

Applied to files:

• docs/design/deployment.md
• docs/security.md

🪛 LanguageTool

docs/design/deployment.md

[uncategorized] ~31-~31: The official name of this software platform is spelled with a capital “H”.
Context: ...topis **not yet built or published by.github/workflows/docker.yml`**, so it is not c...

(GITHUB)

🔇 Additional comments (3)

docker/desktop/Dockerfile (1)

1-1: LGTM!

Also applies to: 15-15

docs/design/deployment.md (1)

25-32: LGTM!

docs/security.md (1)

268-268: LGTM!

---

Walkthrough

This PR pins the docker/desktop/Dockerfile base image (debian:trixie-slim) to a specific content digest rather than relying on the tag alone. The Dockerfile's syntax directive is also updated to include an explicit digest reference. Two new documentation sections are added: one in docs/design/deployment.md explaining that the desktop image is currently not built or published by the main CI workflow, and one in docs/security.md noting that Renovate now auto-updates base-image digests daily for all Dockerfiles, including the desktop image.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR addresses Scorecard alert #309 by pinning base images and documents the desktop image as not-yet-published. However, issue #2033's acceptance criteria (build, publish, sign, verify) are not implemented; the PR only documents the gap.	This PR correctly documents the issue and clears the Scorecard alert, but #2033 acceptance criteria require follow-up work in CI workflows, signing, and verification—tracked as a separate issue intentionally.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main changes: pinning the desktop Dockerfile by digest to address Scorecard #309, and documenting the publish gap.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, explaining the Dockerfile pin, documentation updates, and the tracked follow-up issue.
Out of Scope Changes check	✅ Passed	All changes are in-scope: Dockerfile pinning addresses Scorecard #309, documentation clarifies the desktop image status, and the gap is properly tracked in #2033.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request pins the syntax and base image for the desktop Dockerfile using SHA-256 digests and updates the documentation to include the desktop image in the deployment and security overviews. A correction was suggested for the deployment documentation to clarify that the choice of Debian over Wolfi is due to package availability rather than a lack of glibc support in Wolfi.

[gemini-code-assist]

The explanation "packaged for glibc Debian, not Wolfi" is technically misleading because Wolfi is also a glibc-based distribution (as correctly noted in line 37). The differentiator is the availability of the X11/GUI toolchain in the Debian repositories versus Wolfi's. I suggest clarifying this to avoid implying that Wolfi lacks glibc support.

Suggested change

| `desktop` | Headless virtual-desktop sandbox the agent drives via the desktop tool (Xvfb + fluxbox + xdotool + scrot, plus Python/Tk for GUI deliverables). Spawned on demand by the backend; the `desktop_image_pin` setting defaults to `ghcr.io/aureliolo/synthorg-desktop:latest` | `debian:trixie-slim` pinned by digest in `docker/desktop/Dockerfile`. Debian rather than apko/Wolfi because the X11/GUI toolchain (Xvfb, fluxbox, Tk) is packaged for glibc Debian, not Wolfi |

| `desktop` | Headless virtual-desktop sandbox the agent drives via the desktop tool (Xvfb + fluxbox + xdotool + scrot, plus Python/Tk for GUI deliverables). Spawned on demand by the backend; the `desktop_image_pin` setting defaults to `ghcr.io/aureliolo/synthorg-desktop:latest` | `debian:trixie-slim` pinned by digest in `docker/desktop/Dockerfile`. Debian rather than apko/Wolfi because the X11/GUI toolchain (Xvfb, fluxbox, Tk) is available in Debian but not yet packaged for Wolfi |