fix(rulesets): preserve existing policy and reject incomplete reads (#54)

The branch ruleset applier treated a failed ruleset lookup as permission
to create `Base`, and a failed repository enumeration as a successful
empty run. Updating a baseline also replaced review, scanning,
deployment, bypass and branch-scope settings while retaining only
status-check names.

Repair an existing active repository-owned `Base` or `Optimus-Branch`
additively. Preserve its full policy and other ruleset layers; reject
failed, malformed, truncated, inherited or ambiguous reads. Missing
baselines now require profile-specific provisioning instead of being
created by the legacy hard-coded payload. Add `--repo NAME` for a
bounded pilot, save the pre-change ruleset, recheck for concurrent
edits, and verify the PUT by reading it back. An ambiguous write is
reported without an automatic retry. Dry-run outcomes are reported
separately from verified updates.

Adopt the already-merged Governance reusable workflow at standards
`a8f7249c3c5aef1ed6dfa16e637f13dfde815464`. This brings the consumer the
upstream fixes for the missing lock wrapper and the separation of the
tree allowlist check from credential-dependent administrative
verification. The caller has no `HYPATIA_SCAN_PAT`: the live-policy
advisory reports unavailable coverage, while the tree and lock gates
remain enforced. An authenticated run of the authoritative live-policy
checker independently passed for this repository (`allowed=all`,
`sha_pin=true`).

Package the maintenance CLI in `Containerfile.maintenance`, with an
immutable Ubuntu base, current distribution updates, and the
checksum-verified GitHub CLI 2.100.0 release. The distribution's older
CLI failed the required `--slurp` capability check. Run as UID/GID 10001
and include only the maintenance CLI, its shared library, owner
configuration and tests in the build context. This packages the
maintenance component; it does not claim to package the separate Elixir
TUI or provide a reproducible build of distribution packages.

Validation: 29 offline cases pass, including zero-write failure paths,
preservation of review rules/App-bound checks/bypass actors/scope, a
baseline on the second API page, case-insensitive repository identity,
reordered rules with full parameter checking, and an idempotent second
apply. The original script fails the repository-enumeration negative
control by exiting successfully after the API error. Bash syntax,
ShellCheck, `git diff --check`, the authoritative packaging-policy
check, and `gh actions-lock .github/workflows/governance.yml --no-fix`
pass. The container builds, its entry point works, and all 29 tests pass
as its runtime user with no network, a read-only root filesystem and
dropped Linux capabilities. The test's temporary mount permits its
executable `gh` test double. Governance CI runs the source tests,
container build and restricted-runtime tests.

Live pilot: this repository's Optimus-Branch ruleset #14936593 gained
exactly the missing `non_fast_forward` rule. Full before/after
comparison confirmed no rules removed, all other branch-policy fields
retained, and tag ruleset #18111316 unchanged. A second live apply was a
no-op. Pre-change snapshots and reports were retained in the execution
ledger.

This is the safe repair path for existing baselines. Profile selection,
missing-baseline provisioning, policy changes to existing bypass actors,
and estate-wide rollout remain separate work. The pre-PUT recheck
narrows the concurrent-edit window; it is not an atomic
compare-and-swap.

---------

Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: hyperpolymath

.dockerignore

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: MPL-2.0
+# The maintenance build sends only its runtime and test inputs to the builder.
+**
+!Containerfile.maintenance
+!scripts/
+!scripts/branch-protection-apply.sh
+!scripts/lib/
+!scripts/lib/common.sh
+!config/
+!config/owners.config
+!test/
+!test/branch-protection-apply-test.sh

.github/workflows/actions.lock

@@ -6,7 +6,8 @@ workflows:
     '.github/workflows/codeql.yml':
         - 'actions/checkout@v7.0.1'
         - 'github/codeql-action@v4.37.9'
-    '.github/workflows/governance.yml': []
+    '.github/workflows/governance.yml':
+        - 'actions/checkout@v7.0.1'
     '.github/workflows/hypatia-scan.yml': []
     '.github/workflows/label-triage.yml': []
     '.github/workflows/labels.yml': []

.github/workflows/governance.yml

@@ -1,5 +1,5 @@
-# SPDX-License-Identifier: MPL-2.0
 # This workflow is managed by gh actions-lock.
+# SPDX-License-Identifier: MPL-2.0
 name: Governance
 
 on:
@@ -15,4 +15,30 @@ permissions:
 
 jobs:
   governance:
-    uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@fad242d35291de1898242d6737ba02b74a59a2f2
+    uses: hyperpolymath/standards/.github/workflows/governance-reusable.yml@a8f7249c3c5aef1ed6dfa16e637f13dfde815464
+  ruleset-regression:
+    name: Ruleset repair regression
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          persist-credentials: false
+      - name: Check shell syntax and offline ruleset behaviour
+        shell: bash
+        run: |
+          bash -n scripts/branch-protection-apply.sh test/branch-protection-apply-test.sh
+          bash test/branch-protection-apply-test.sh
+      - name: Build the maintenance CLI package
+        run: docker build --file Containerfile.maintenance --tag git-scripts-maintenance:test .
+      - name: Exercise the package without network or a writable root filesystem
+        run: |
+          # The suite creates an executable gh test double in /tmp.
+          docker run --rm --network none --read-only --cap-drop ALL \
+            --security-opt no-new-privileges \
+            --tmpfs /tmp:rw,exec,nosuid,nodev,uid=10001,gid=10001 \
+            --tmpfs /state:rw,nosuid,nodev,uid=10001,gid=10001 \
+            --entrypoint bash git-scripts-maintenance:test \
+            /opt/git-scripts/test/branch-protection-apply-test.sh

Containerfile.maintenance

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MPL-2.0
+# A runnable package for the branch-policy maintenance CLI and its tests.
+FROM docker.io/library/ubuntu:24.04@sha256:4fbb8e6a8395de5a7550b33509421a2bafbc0aab6c06ba2cef9ebffbc7092d90
+
+RUN apt-get update \
+    && apt-get upgrade --no-install-recommends -y \
+    && apt-get install --no-install-recommends -y \
+       bash ca-certificates coreutils curl diffutils findutils gawk git grep jq sed util-linux \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd --gid 10001 maintenance \
+    && useradd --uid 10001 --gid 10001 --no-create-home --shell /usr/sbin/nologin maintenance \
+    && mkdir -p /state \
+    && chown 10001:10001 /state
+
+# Ubuntu 24.04's gh 2.45 lacks the --slurp capability used by the applier.
+# Install the upstream immutable release and verify its published asset digest.
+RUN cli_arch="$(dpkg --print-architecture)" \
+    && case "${cli_arch}" in \
+       amd64) cli_sha=698c8d88cc19cc92bfe96bad58d10b2a5b274c52433d6dc57799c81f6139d5fc ;; \
+       arm64) cli_sha=33ccd2ad7ce639c927e1cb209e36555b0e1fbb89f7a38239c0568040ec758612 ;; \
+       *) echo "Unsupported CLI architecture: ${cli_arch}" >&2; exit 1 ;; \
+       esac \
+    && curl --fail --location --retry 3 \
+       "https://github.com/cli/cli/releases/download/v2.100.0/gh_2.100.0_linux_${cli_arch}.deb" \
+       --output /tmp/gh.deb \
+    && printf '%s  %s\n' "${cli_sha}" /tmp/gh.deb | sha256sum --check - \
+    && dpkg --install /tmp/gh.deb \
+    && rm /tmp/gh.deb
+
+WORKDIR /opt/git-scripts
+COPY scripts/branch-protection-apply.sh scripts/branch-protection-apply.sh
+COPY scripts/lib/common.sh scripts/lib/common.sh
+COPY config/owners.config config/owners.config
+COPY test/branch-protection-apply-test.sh test/branch-protection-apply-test.sh
+
+ENV GS_BACKUP_DIR=/state/backups \
+    GS_STATE_DIR=/state/snapshots \
+    GS_LOCK_DIR=/state/locks \
+    GS_REPORT_DIR=/state/reports \
+    XDG_CACHE_HOME=/state/cache \
+    XDG_CONFIG_HOME=/state/config
+USER 10001:10001
+
+# Check the packaged files as the runtime user. The suite mocks every gh call.
+RUN bash -n scripts/branch-protection-apply.sh test/branch-protection-apply-test.sh \
+    && gh api --help | grep -q -- --slurp \
+    && bash test/branch-protection-apply-test.sh
+
+ENTRYPOINT ["bash", "/opt/git-scripts/scripts/branch-protection-apply.sh"]
+CMD ["--help"]

README.adoc

@@ -45,6 +45,37 @@ mix compile
 mix escript.build
 ----
 
+=== Branch-policy maintenance package
+
+`Containerfile.maintenance` packages the Bash branch-policy repair CLI with its
+GitHub CLI, JSON and system-tool dependencies. It includes the offline regression
+suite and runs as UID/GID 10001. This package covers the maintenance CLI; the
+Elixir TUI build above remains a separate component. Guix is the estate's primary
+packaging route; this container provides a buildable maintenance environment on
+hosts where Guix is unavailable.
+
+[source,bash]
+----
+podman build -f Containerfile.maintenance -t localhost/git-scripts-maintenance .
+podman run --rm --network none --read-only --cap-drop ALL \
+  --security-opt no-new-privileges \
+  --tmpfs /tmp:rw,nosuid,nodev,uid=10001,gid=10001 \
+  --tmpfs /state:rw,nosuid,nodev,uid=10001,gid=10001 \
+  localhost/git-scripts-maintenance --help
+----
+
+For an authenticated dry run, allow network access and pass an existing
+`GH_TOKEN` with `--env GH_TOKEN`. Select a single repository with
+`--repo NAME --dry-run`. An actual repair needs repository Administration write
+permission and a persistent `/state` volume for its pre-change snapshots and
+reports. The CLI never creates missing baselines or changes tag rulesets.
+
+The base image is pinned by digest. Distribution packages are resolved at build
+time, so rebuilding on another date can change package versions; the result is
+not claimed to be a reproducible build. Governance CI builds the image and runs
+its tests with networking disabled, a read-only root filesystem and no Linux
+capabilities. Docker can run the same commands and OCI image.
+
 == Implementation Details
 
 Each function is implemented as an Elixir module: