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
33 changes: 25 additions & 8 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
@@ -1,16 +1,33 @@
# SPDX-License-Identifier: MPL-2.0
# CodeRabbit configuration. Schema: https://coderabbit.ai/integrations/schema.v2.json
#
# Docstring Coverage pre-merge check is pinned to `mode: warning` as an explicit
# estate decision rather than left to the vendor default. Some estate repos'
# rulesets require the `CodeRabbit` status context; an `error` mode would make
# them unmergeable at today's docstring-coverage baseline. Raise it per repo only
# once that repo's coverage clears the threshold.
# CodeRabbit reviews changes; humans and authorised agents own changes.
# Canonical estate language policy:
# https://github.com/metadatastician/standards/blob/main/3-practice/LANGUAGE-POLICY.adoc
# This template must never permit unsolicited AI-generated fixes/commits.
reviews:
path_instructions:
- path: "**/*"
instructions: >-
Enforce the canonical estate language policy: Python is prohibited
for all NEW work, without exceptions. Do not suggest Python
implementations or tests, and flag newly added/modified Python
files or dependency manifests as policy violations. Use the owning
project's approved language and runtime. Pre-existing third-party
code is not permission to author new Python. Do not demand language
migrations of unrelated upstream dependencies as cosmetic PR work.
pre_merge_checks:
docstrings:
mode: warning
threshold: 80
finishing_touches:
docstrings:
enabled: true
enabled: false
unit_tests:
enabled: false
simplify:
enabled: false
autofix:
enabled: false
fix_ci:
enabled: false
resolve_merge_conflict:
enabled: false
55 changes: 0 additions & 55 deletions .cursorrules

This file was deleted.

6 changes: 3 additions & 3 deletions .devcontainer/Containerfile
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,11 @@ RUN apk update && apk add --no-cache \

# Nickel (the .machine_readable contracts): the same verified release CI uses
# (.github/workflows/estate-rules.yml). Bump the version and both digests together.
ARG NICKEL_VERSION=1.17.0
ARG NICKEL_VERSION=1.18.0
RUN set -eu; \
case "$(uname -m)" in \
x86_64) asset=nickel-x86_64-linux; sum=afcdfa6e0fff31760cf229e85997456c02c00b8b3b84ff38f897ac7b3f39ae34 ;; \
aarch64) asset=nickel-arm64-linux; sum=9d7e027fde829b5788c92231c27fcfc926ee841d0716d655cee202c9f582e0c0 ;; \
x86_64) asset=nickel-x86_64-linux; sum=9cba4dd65ae9915ec61f73033aafcff307a377665a83fd8f530df086763318cb ;; \
aarch64) asset=nickel-arm64-linux; sum=626571e76b66523f454abb373fda4935e2b2685a008ebb8a783b0d20321ffdbd ;; \
*) echo "no Nickel release binary for $(uname -m)" >&2; exit 1 ;; \
esac; \
curl --proto '=https' --proto-redir '=https' -fsSL \
Expand Down
1 change: 1 addition & 0 deletions .gitbot-fleet/enrolment.json
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
{"reporters":{"accessibilitybot":{"enrolled":false,"reason":"template default: enrol once the repository serves HTML"},"cipherbot":{"enrolled":false,"reason":"template default: enrol once the repository implements cryptography"},"echidnabot":{"enrolled":false,"reason":"template default: enrol once the repository carries proofs and an ECHIDNA engine is configured"},"finishingbot":{"enrolled":true,"title":"finishingbot (release readiness)"},"glambot":{"enrolled":true,"title":"glambot (presentation quality)"},"panicbot":{"enrolled":false,"reason":"panic-attack is already graded by the verdict grid's own panic-attack row, from static-analysis-gate.yml evidence; enrolling panicbot would report one scanner twice and give two rows that can disagree"},"rhodibot":{"enrolled":true,"title":"rhodibot (RSR compliance)"},"seambot":{"enrolled":false,"reason":"template default: enrol once a seam register exists at spec/seams/seam-register.json"},"sustainabot":{"enrolled":false,"reason":"reserved fleet slot; no adapter exists (gitbot-fleet bots/sustainabot/README.adoc)"}},"schema":1}
35 changes: 35 additions & 0 deletions .gitbot-fleet/report-backs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# gitbot-fleet report-backs

One JSON envelope per enrolled fleet member, `<member>.json`, in the shape
metadatastician/standards `docs/VERDICT-GRID-SPEC.adoc` defines ("The
report-back envelope"). The Hypatia verdict grid gives every member named in
`../enrolment.json` one row; the row stays **orange** ("enrolled, but no
report-back was received") until an envelope is present here when the grid
renders.

**This directory is empty in git on purpose, and stays so.** Envelopes are
produced per run by the `fleet` job of `.github/workflows/fork-governance.yml`
(gitbot-fleet `scripts/fleet-report-back.sh`), uploaded as the
`fleet-report-backs` artifact, and read from that artifact at render time by the
`verdict` job of the same workflow, which passes this directory to the grid
renderer. A committed envelope would be stale evidence about an older commit, so
none is ever committed. Do not add a placeholder to turn a row green; only a
real run may.

Two related rules:

* an enrolled member with **no** envelope renders **orange** ("enrolled, but no
report-back was received") — never green, and never grey
(`docs/HYPATIA-RULE-ORDER.adoc`);
* a member that reports back without an enrolment entry still gets a row from
its envelope alone. Enrolment decides what a *missing* envelope means; it does
not decide what a present one is allowed to say
(metadatastician/standards `docs/VERDICT-GRID-SPEC.adoc`).

When instantiating a repository from this template, edit `../enrolment.json`:
enrol what is true of the repository, with a reason for every member that does
not apply. The template defaults enrol rhodibot, finishingbot and glambot,
which apply to every estate repository. Adoption guide: standards
`3-practice/fork-governance/ADOPTION.adoc` §8.

Only files matching `*.json` are read, so this README is inert.
11 changes: 7 additions & 4 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,13 @@ Copyright (c) Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
# Security Policy

<!--
The token vocabulary lives in .machine_readable/ai/PLACEHOLDERS.adoc, not here.
The token vocabulary is not restated here (`just repo-init` substitutes the tokens).
This file used to restate it in a "delete before publishing" block, but `just
init` substitutes tokens inside comments too — so the block's own instructions
were rewritten into nonsense and then shipped, because nothing deleted it.
Where it lives: the `placeholders` document (`repo-document:…#placeholders`),
registered under (documents) in *_chora.deed. If that page is gone, contact the maintainer
(docs/MAINTAINERS.adoc), or ask an AI assistant to read *_chora.deed for its current location.
-->

We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions.
Expand Down Expand Up @@ -307,7 +310,7 @@ To stay informed about security updates:

- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts"
- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/sholes/security/advisories)
- **Release notes**: Security fixes noted in [CHANGELOG](../CHANGELOG.md)
- **Release notes**: Security fixes noted in [CHANGELOG](../CHANGELOG.adoc)

### Update Policy

Expand Down Expand Up @@ -355,8 +358,8 @@ When using sholes, we recommend:
## Additional Resources

- [Security Advisories](https://github.com/hyperpolymath/sholes/security/advisories)
- [Changelog](../CHANGELOG.md)
- [Contributing Guidelines](CONTRIBUTING.md)
- [Changelog](../CHANGELOG.adoc)
- [Contributing Guidelines](../CONTRIBUTING.adoc)
- [CVE Database](https://cve.mitre.org/)
- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1)

Expand Down
123 changes: 123 additions & 0 deletions .github/actions/squabble/README.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
= squabble action — install the pinned, attested squabble binary
:toc: preamble

A composite action that installs one exact squabble release binary in a
workflow and, optionally, runs it. It refuses any file whose sha256 is not
the pinned digest, and any file whose build provenance does not trace back
to this repository's release workflow at the pinned tag and source commit.
Nothing is executed until both checks pass.

== Usage

Pin the action to a full commit SHA of this repository, never to a branch or
tag:

[source,yaml]
----
# Install only: squabble is on PATH from the next step on.
- uses: hyperpolymath/cicd-squabbler/.github/actions/squabble@<40-hex sha>
id: squabble
- run: squabble --version
----

Run mode passes `args` to squabble, one argument per line, taken literally
(no shell parsing, no globbing; blank lines are dropped). The step fails
when squabble exits non-zero, and `run.sh` records the exit code as the
`exit-code` output (see <<_not_yet_tested>> for what CI has not yet shown).

[source,yaml]
----
- uses: hyperpolymath/cicd-squabbler/.github/actions/squabble@<40-hex sha>
with:
args: |
verify-satisfied
${{ github.repository }}
${{ github.event.pull_request.number }}
token: ${{ steps.app-token.outputs.token }}
----

=== Inputs and outputs

[cols="1,3"]
|===
| `args` (input) | squabble's arguments, one per line. Empty (the default) means install only.
| `token` (input) | `GH_TOKEN` for squabble in run mode. Defaults to `github.token`. `verify-satisfied` reads branch rules, which need *Administration: read*; `github.token` cannot hold that, so pass a GitHub App installation token for it.
| `path` (output) | Absolute path of the installed binary.
| `exit-code` (output) | squabble's exit code in run mode; empty when `args` is empty.
|===

The download and the attestation check always use the workflow's own
`github.token`, never `token`: an App token minted for the caller's
repository need not reach this one. This repository is public, so
`github.token` is enough for both.

== What is checked, in order

`install.sh` does all of this before the binary is made executable:

. The runner is Linux on x86_64. That is the only asset published.
. The release asset is downloaded into a fresh directory.
. Its sha256 must equal the pinned digest.
. `gh attestation verify --format json` must accept it with this repository,
the signer workflow `.github/workflows/release.yml`, the source ref
`refs/tags/<tag>`, the pinned source commit, the SLSA provenance v1
predicate, and `--deny-self-hosted-runners`. The JSON is then read
back: it must be a non-empty array in which every result names the asset
with the pinned digest. The JSON form is used because the plain-text output
has been seen empty, with exit 0, when stdout is not a terminal.
. Only then is the file made executable, and it must report the pinned
version (`squabble 0.1.0`).

== Pins

[cols="1,3"]
|===
| Release tag | `v0.1.0` (a locator, not a trust anchor)
| Asset | `squabble-x86_64-linux-musl`
| Asset sha256 | `6cbeb4577d83ccf2dea3405a3afb0d34b7fee422af73f2113d413ea7edba026c`
| Source commit | `b854d17abc0dce296719a349ebe856ff945cf03e`
| Signer workflow | `hyperpolymath/cicd-squabbler/.github/workflows/release.yml`
|===

== Bumping to a new release

Read every value from the release itself, never from a tag name alone.

. `gh release download <tag> --repo hyperpolymath/cicd-squabbler --pattern
squabble-x86_64-linux-musl --pattern SHA256SUMS`, then `sha256sum -c
SHA256SUMS --ignore-missing`.
. Find the commit the tag points to: `git rev-parse <tag>^{commit}`.
. Run `gh attestation verify` on the asset with the flags `install.sh` uses
and that commit as `--source-digest`. It must pass.
. Set `SQUABBLE_TAG`, `SQUABBLE_SHA256` and `SQUABBLE_SOURCE_DIGEST` in
`install.sh`, and update any version reference in
`.github/workflows/squabble.yml`.
. Run `bash tests/workflows/squabble_gate_test.sh`. It must end with every
planned case run and none failed.

== How it is tested

`tests/workflows/squabble_gate_test.sh` exercises the action guards and the
companion required-context gate with Silence + Firing + Setup cases: the
`verify_digest` SHA256 mismatch check, the `check_attestation_json` SLSA
attestation checks (empty array, matching digest, mismatched digest),
`run.sh` exit-code propagation (`0` and blocking exit `4`) against a stand-in
binary, and `scripts/check-required-contexts.sh` against missing producers,
path-filtered workflows, unmapped ruleset contexts, and `gh pr merge --admin`
bypass invocations.

`.github/workflows/squabble.yml` runs `install.sh` and `run.sh` on a real
runner against this repository's `.github/workflows` directory and verifies
`scripts/check-required-contexts.sh`.

=== Not yet tested

GitHub's own evaluation of `action.yml` (composite inputs, outputs and the
`if:` on the run step) is not exercised here. This repository has an
`actions.lock`, and the lockfile does not support local-path actions, so a
workflow here cannot call the action as `uses: ./.github/actions/squabble`.
It is first exercised by a caller that pins the action at a merged commit of
`main`, which the lockfile does support. That caller should check in
particular that `exit-code` is readable when the run step fails.
68 changes: 68 additions & 0 deletions .github/actions/squabble/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# SPDX-License-Identifier: MPL-2.0
#
# squabble: install the pinned, attested squabble release binary and,
# optionally, run it. Call it pinned to a commit of this repository:
#
# uses: hyperpolymath/cicd-squabbler/.github/actions/squabble@<40-hex sha>
#
# The binary itself is pinned inside install.sh by sha256 and by its
# build-provenance attestation. See README.adoc next to this file.
#
# This file is KYAML (standards YAML-POLICY, D280). Regenerate it with
# standards/scripts/kyaml-format.sh after an edit; keep each run: to one line
# that calls a script, so the KYAML stays readable.
{
name: "squabble",
description: "Install the pinned squabble release (sha256 and build attestation checked), and optionally run it.",
author: "hyperpolymath",
inputs: {
args: {
description: "Arguments for squabble, one per line, taken literally. Empty means install only.",
required: false,
default: "",
},
token: {
description: "GH_TOKEN for squabble itself in run mode. verify-satisfied needs Administration:read, which github.token cannot hold, so pass an App token for it. Installing always uses github.token.",
required: false,
default: "${{ github.token }}",
},
},
outputs: {
path: {
description: "Absolute path of the installed squabble binary.",
value: "${{ steps.install.outputs.path }}",
},
exit-code: {
description: "squabble's exit code in run mode; empty when args is empty.",
value: "${{ steps.run.outputs.exit-code }}",
},
},
runs: {
using: "composite",
steps: [
# Install with the workflow's own token, never the caller's run-mode token:
# an App installation token for the caller's repo need not reach this one.
{
name: "Install pinned squabble (sha256 + attestation)",
id: "install",
shell: "bash",
env: {
GH_TOKEN: "${{ github.token }}",
},
run: "bash \"${GITHUB_ACTION_PATH}/install.sh\"",
},
{
name: "Run squabble",
id: "run",
if: "inputs.args != ''",
shell: "bash",
env: {
GH_TOKEN: "${{ inputs.token }}",
SQUABBLE_ARGS: "${{ inputs.args }}",
SQUABBLE_BIN: "${{ steps.install.outputs.path }}",
},
run: "bash \"${GITHUB_ACTION_PATH}/run.sh\"",
},
],
},
}
Loading
Loading