fix(tag-ruleset-canon): enumerate and probe through the App installation

[hyperpolymath]

Summary

tag-ruleset-canon.yml mints one GitHub App installation token per owner (RULESET_APP_ID, #1208). scripts/apply-tag-ruleset-canon.sh still assumed a PAT, so both workflow steps would have failed on their first App run. This PR makes the applier work under an installation token and leaves PAT behaviour unchanged.

Three defects are fixed:

1. hyperpolymath step: user/repos under an App token. That endpoint needs a user identity, so it answers an installation token (ghs_…) with 403 Resource not accessible by integration. Under set -e the run died before it examined any repository. Under an installation token the applier now lists installation/repositories (private repos included, archived ones dropped). If that listing fails, the run dies and names the endpoint.
2. metadatastician step: write probe outside the installation. The apply-mode write probe always self-PUT GITHUB_REPOSITORY (hyperpolymath/standards). An installation on metadatastician cannot write that repo, so a capable credential got a false exit 3 ("credential cannot WRITE rulesets"). Under an installation token the probe now self-PUTs a repository-level tag ruleset inside its own installation. It skips org-inherited rulesets, because a per-repo PUT of those 404s (O6 propagation: four contradictions between the ruling and the committed rulesets #1032). A credential that really cannot write still stops the run with exit 3.
3. ESTATE_ORGS='' meant metadatastician. The hyperpolymath step sets ESTATE_ORGS: '', but ${ESTATE_ORGS:-metadatastician} treated the empty string as unset. That step would therefore also sweep metadatastician repos its token cannot write. It is now ${ESTATE_ORGS-metadatastician}: an explicit empty value means no orgs, and the default still applies when the variable is unset.

Unchanged under a PAT (the ESTATE_ADMIN_TOKEN fallback): targets come from user/repos and the probe self-PUTs GITHUB_REPOSITORY. The workflow file is not touched.

No tracking issue. This implements the owner's ruling of 2026-10-08: "Fix in a standards PR now".

Type of change

• 🐛 Bug fix (non-breaking change that fixes an issue). Under a PAT nothing changes. Under an App token the applier now runs where before it crashed.
• ✨ New feature. No new capability; this makes the existing App path work.
• 💥 Breaking change. The one behaviour change is that an explicit ESTATE_ORGS='' now means no orgs. The only caller that sets it to '' is the hyperpolymath step of tag-ruleset-canon.yml, which wants exactly that.
• 🕳️ Soundness fix. The ruleset canon and the convergence logic are unchanged.
• 📖 Documentation. Only the script's header comment changes, to describe --skip-user and ESTATE_ORGS under an App token.
• 🧹 Refactor / tech debt. Not behaviour-preserving (see Bug fix).
• ⚡ Performance. Not applicable.
• 🔧 Build / CI / tooling. An estate maintenance script and a new test for it.

📌 New pins

• Head SHA: e39d890c6de1f56faa6bdba1f02aca20234f4aed
• None. No uses: SHA, actions.lock entry, lockfile record or container digest is added or changed. No workflow file is touched.

How has this been verified?

All commands were run in the worktree on Debian 13 (WSL2).

• New scripts/tests/apply-tag-ruleset-canon-test.sh → passed=14 failed=0. It runs the applier against a stub gh that serves fixtures and refuses what GitHub refuses:
  • ghs_ on user/repos → 403;
  • an installation token writing outside its installation → 403;
  • a per-repo PUT of an org-inherited ruleset → 404.
  • Planted positives (3): the stub is shown to refuse each of those, so no case passes vacuously.
  • Cases (6):
    • App token with ESTATE_ORGS='': targets are exactly the installation's non-archived repos, both CONVERGED, rc 0, and user/repos is never called.
    • PAT: user/repos.
    • PAT probe: still GITHUB_REPOSITORY.
    • A failed installation listing: non-zero rc, no report lines, the endpoint named.
    • Org App token in apply mode with GITHUB_REPOSITORY=hyperpolymath/standards: exactly one probe PUT, to the repo-level ruleset inside the installation. The org-inherited repo listed first is skipped and reported ORG-INHERITED. rc 0.
    • Write-denied org token: still exit 3.
  • Mutants (4), each bash -n-checked and each killed:
    • the ghs_* detection disabled, killed by 2 cases;
    • ${ESTATE_ORGS:-…} restored;
    • the source_type == "Repository" filter removed from the probe;
    • the listing failure swallowed.
• The origin/main applier through the same harness → 5 cases failed:
  • App token: rc=1 on the user/repos 403, as was the failed-listing case;
  • PAT with ESTATE_ORGS='': metadatastician/delta was swept;
  • org probe: false rc=3, no write attempted.
• bash tests/test_tag_ruleset_canon.sh → passed=31 failed=0 (the existing structural guards, properties 1–14).
• shellcheck on both files → rc 0. One SC2016 is disabled on a single line, with a reason: the ${…} there is sed text to match.
• .githooks/docstring-scan.sh --worktree --check → functions=17 documented=17 coverage=100.00%.
• bash scripts/run-shell-test-suite.sh → 80 of 82 test files pass. The 2 failures are pre-existing on main: scripts/tests/build-registry-test.sh (2 ❌) and scripts/tests/build-scorecards-test.sh (10 ❌) fail identically in a clean detached worktree of origin/main 900c42c7. This PR touches neither generator nor either test.
• Pre-commit hooks: all passed (gitleaks, SPDX, sha-pins, actions-lock, permissions, codeql, bot-directives).
• CI on this head (Self Test run 37861614216): scripts/tests/apply-tag-ruleset-canon-test.sh → passed=14 failed=0. The run reports 2 of 82 test file(s) failed, and they are the same two pre-existing files.

Horizon: this is a local stub of GitHub's behaviour, not a live run. The live acceptance run is the next step. It needs the ruleset App to be created and installed on both owners, and RULESET_APP_ID / RULESET_APP_PRIVATE_KEY to be set on this repo. Then tag-ruleset-canon is dispatched with apply=false.

Checklist

• My commits are signed: one commit, git log --show-signature → G, ED25519.
• I ran the project's own checks/tests locally and they pass, apart from the 2 test files that fail identically on main (see above).
• New files carry the correct SPDX-License-Identifier: the new test is MPL-2.0. No existing file was relicensed.
• Docs are updated, and no public claim now overstates what the code does. The script header now says what --skip-user and ESTATE_ORGS='' do under an App token.
• I have not introduced a soundness hole. The probe still refuses a credential that cannot write (shown by the write-denied case), and the convergence and comparison logic is untouched.

Notes for reviewers

• Why detect ghs_ rather than try user/repos and fall back? A 403 from user/repos is the same 403 a mis-scoped PAT gets. A fallback would quietly turn a broken PAT into "list whatever installation/repositories says". The token prefix is the one unambiguous signal. GITHUB_TOKEN is also ghs_. Its installation lists only this repo, so in apply mode the write probe PUTs here, gets 403 (no administration:write) and stops the run with exit 3, as before. In a dry run it would report on this one repo only.
• list_installation_repos runs at most once. Both the probe and the enumeration need it. It is called in the main shell, never inside $(…), so the once-only flag survives.
• Out of scope: scripts/apply-workflow-pins-remote.sh lists targets with users/<owner>/repos, which returns public repos only. That is recorded as a finding, not fixed here.
• Red check deferred: Registry + topology in sync also fails on main at 900c42c7. It has been red since bbcc722b (chore(deps): bump rustls from 0.23.37 to 0.23.45 in /rhodium-standard-repositories/satellites/rsr-certifier in the cargo group across 1 directory #1206). This PR touches neither the registry nor its generator. Tracked by Two unowned reds on #1160: self-ci Haskell job builds at root with no cabal.project; registry drift on main #1161 §2, which has acceptance criteria.
• Red check deferred: Repo self-tests also fails on main at 900c42c7 (Self Test run 37770790241). The same two files fail there and on this head: scripts/tests/build-registry-test.sh and scripts/tests/build-scorecards-test.sh, for the cause in the row above (REGISTRY.a2ml drift). Tracked by Two unowned reds on #1160: self-ci Haskell job builds at root with no cabal.project; registry drift on main #1161 §2. The fix, either regenerating the registry or retiring the check along with .a2ml, is the owner's ruling, so this PR does not regenerate the registry.

🤖 Generated with Claude Code

https://claude.ai/code/session_015bTuGfwCcvjrmNFejydTML

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 26 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 71281659-6a14-49df-b4f4-32d6497ff01d

📥 Commits

Reviewing files that changed from the base of the PR and between 900c42c and e39d890.

📒 Files selected for processing (2)

• scripts/apply-tag-ruleset-canon.sh
• scripts/tests/apply-tag-ruleset-canon-test.sh

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

K9 contract conformance

run https://github.com/hyperpolymath/standards/actions/runs/37861614231

K9 normative contract typecheck

k9_contract.ncl typechecks

K9 contract self-test

== the bash mirrors cannot drift from the normative contract ==
ok   leash_levels mirrors k9_contract.ncl
ok   core_capabilities mirrors k9_contract.ncl
ok   contract_version mirrors k9_contract.ncl
ok   schema_major mirrors k9_contract.ncl
== capability arithmetic (§8) ==
ok   capability_ok fs.read accepted
ok   capability_ok rollback.apply accepted
ok   capability_ok x-acme.gpu.alloc accepted
ok   capability_ok x-acme rejected
ok   capability_ok x-.gpu rejected
ok   capability_ok fs.delete rejected
ok   capability_ok  rejected
== the extractor ==
ok   extracts pedigree.security.leash
ok   extracts pedigree.component_type
ok   extracts pedigree.metadata.name
ok   pedigree leash is not reported as top-level leash
ok   required_capabilities for a quiet component
ok   required_capabilities follows allow_network
== the envelope strip keeps line numbers (§3.6) ==
ok   line 1 becomes a comment
ok   line count is preserved
ok   schema_version stays on line 5
== L3: signature presence is not verification (§10) ==
ok   no verifier -> K9-C001 is SKIPPED, never a pass
ok   the skip states presence does not authorise 'Hunt
ok   verifier accepts -> verdict 'Verified, no K9-C001 finding
ok   verifier refuses -> K9-C001 error, verdict 'Rejected
== the fixture runner's attribution cannot be fooled by a filename ==
ok   every extracted finding is well-formed rule+layer
ok   the rule that really fired is attributed
ok   a rule named only in the filename is NOT attributed
ok   K9-C001 is present as a skipped finding
ok   and that same finding is NOT extractable as a rejection
== no Nickel reserved word is used as an identifier ==
ok   the contract and all 27 fixtures avoid Nickel's reserved words

self-test: all assertions passed

K9 conformance fixtures

== positive controls (must pass) ==
ok   extension-capability.k9.ncl
ok   extension-fields.k9.ncl
ok   hunt-fully-granted.k9.ncl
ok   kennel-data.k9.ncl
ok   library-base.ncl
ok   yard-typed-config.k9.ncl

== negative controls (must fail, by the named rule) ==
ok   L0-K9-E001-bad-magic.k9.ncl (rejected by K9-E001 at L0)
ok   L0-K9-E002-nul-byte.k9.ncl (rejected by K9-E002 at L0)
ok   L0-K9-E003-crlf.k9.ncl (rejected by K9-E003 at L0)
ok   L0-K9-E004-no-spdx.k9.ncl (rejected by K9-E004 at L0)
ok   L0-K9-E005-unclaimed-body.k9.ncl (rejected by K9-E005 at L0)
ok   L0-K9-S012-library-with-pedigree.ncl (rejected by K9-S012 at L0)
ok   L0-K9-S014-stray-leash.ncl (rejected by K9-S014 at L0)
ok   L1-K9-S001-no-pedigree.k9.ncl (rejected by K9-S001 at L1)
ok   L1-K9-S002-wrong-major.k9.ncl (rejected by K9-S002 at L1)
ok   L1-K9-S003-todo-component-type.k9.ncl (rejected by K9-S003 at L1)
ok   L1-K9-S004-unknown-leash.k9.ncl (rejected by K9-S004 at L1)
ok   L1-K9-S005-missing-name.k9.ncl (rejected by K9-S005 at L1)
ok   L1-K9-S006-unknown-capability.k9.ncl (rejected by K9-S006 at L1)
ok   L1-K9-S007-ungranted-flag.k9.ncl (rejected by K9-S007 at L1)
ok   L1-K9-S008-hunt-signature-not-required.k9.ncl (rejected by K9-S008 at L1)
ok   L1-K9-S009-hunt-no-signature-block.k9.ncl (rejected by K9-S009 at L1)
ok   L1-K9-S010-hunt-empty-side-effects.k9.ncl (rejected by K9-S010 at L1)
ok   L1-K9-S011-recipes-at-yard.k9.ncl (rejected by K9-S011 at L1)
ok   L1-K9-S013-dangling-import.k9.ncl (rejected by K9-S013 at L1)
ok   L2-K9-N001-two-segment-version.k9.ncl (rejected by K9-N001 at L2)
ok   L2-K9-N001-wrong-field-type.k9.ncl (rejected by K9-N001 at L2)

fixtures: 6 positive, 21 negative (0 needing nickel), 0 failure(s)

K9 corpus conformance (L2)

[validate-k9] debt rhodium-standard-repositories/rsr-compliance-checklist.k9.ncl (fail) — K9-N001 K9-S004 K9-S005 K9-S014 (grandfathered; touching it makes it blocking)
[validate-k9] 14 conforming, 1 grandfathered (layer all, contract v1.0.0)

[sonarqubecloud]

Quality Gate passed

Issues
55 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud