Skip to content

fix(governance): stop routing agents to retired settings tooling - #8

Merged
zoeyrose merged 4 commits into
mainfrom
fix/retired-settings-tooling-guidance
Nov 14, 2026
Merged

zoeyrose merged 4 commits into
mainfrom
fix/retired-settings-tooling-guidance

Conversation

@zoeyrose

@zoeyrose zoeyrose commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Summary

The atrinik-github-governance skill still sent agents to the retired atrinik/github-settings tooling. It told them to follow github-settings/AGENTS.md as a script runbook and to "run the publisher plan before --apply". The publisher, audit and Project sync are now retired. This PR rewrites the skill's settings guidance to match how settings are handled now, records the edit in the package provenance, and bumps the plugin to 1.0.2.

atrinik-issue-delivery and atrinik-program-delivery read the In progress status name from github-settings/config/planning.json. That file stays in atrinik/github-settings, so those references keep working and are not changed. A new test pins them.

Intent brief

  • Goal: stop the plugin's skills from routing agents to retired tooling that works under the owner's login, and describe the current way to change settings.
  • Decisions and why:
    • Only the governance SKILL.md changes. The two delivery skills need nothing that was retired: they set a Project status by hand and read one file that stays. Leaving them alone keeps the provenance change to a single record.
    • The skill points to the current README.md and AGENTS.md of atrinik/github-settings for the details instead of copying them. That follows this repository's rule that the owning repository holds operational authority. It also says the old bin/ scripts must not be run "even where older text still describes them", because that repository's AGENTS.md on main still documents the publisher until its own retirement PR merges.
    • The ban covers that repository's bin/ scripts by name and wherever they are found: the current tree, an old checkout or a release. On main today its README.md and AGENTS.md still document bin/publish and the planning scripts, so the skill gives no allowance for "tools its README documents". The planned read-only check (step 6 of the settings redesign) is not allowed yet; the PR that adds it must update this skill and its marker test (see Limitations / follow-up).
    • Workflow changes no longer make Actions allowlist or ruleset edits a standing step. The skill says to report the change a workflow needs and make it only when the task asks for it, matching step 4.
    • Provenance follows the precedent of docs(classic): align LLVM execution guidance #4. The edit is recorded as a local_authored_updates entry, with source 86ea824 (the commit holding the final SKILL.md bytes) and baseline 98196a5 (current main). The offline validator now allows exactly one reviewed (source, baseline) pair per local path, in place of one global pair. The CI allowlist adds the two full commit IDs.
    • Version 1.0.2 (patch): this corrects guidance and does not change any invocation policy or skill set.
  • Constraints: the plugin is MIT and public, so the text names no private hosts or paths. Skill byte budgets still hold (imported SKILL.md total is well under 62,500). The Required checks and Conventional PR title job names are unchanged.
  • Out of scope: the atrinik/github-settings retirement PR itself, the planned read-only check and baselines, any GitHub settings, rulesets or secrets, and the disabled atrinik-development@zoey-local copy.

Implementation / behavior

  • skills/atrinik-github-governance/SKILL.md:
    • Step 3: read the workspace guide and the current README.md/AGENTS.md of atrinik/github-settings, then compare them with the live API. The publisher, audit and Project sync are retired. Never run its bin/ scripts (publish*, audit, sync-project and the rest), with or without --apply, from its current tree, an old checkout or a release, even where its README.md or AGENTS.md still describes them.
    • Step 4: organization-wide rules live in organization rulesets aimed at all repositories, not lists of names. A required-check ruleset targets its one repository. Change a setting by hand under the owner's login only when the current task asks for it. Export the object first, re-read it live afterwards, and record the change in the same task. Never record a setting for later application.
    • Change policy coherently: when workflows change, update their permissions and dependency pins, and report any Actions allowlist, ruleset or required-check change they need; make it only if the task asks for it (step 4).
    • Validate and hand off: the "publisher plan mode / inspect the plan before apply" step is replaced by a fresh live read of each changed object. The rollback note now uses the export taken before the change.
    • Fixes the PR-only step range (skip steps 3–5; there are five steps).
  • provenance.json: new local_authored_updates record for that file (source/destination blob c0a5c17, baseline blob 95cf884, MIT license blob).
  • tests/test_package.py: LOCAL_UPDATE_ROLES maps each local path to its one approved pair. A new test case refuses an approved revision that belongs to another path's pair. The manifest test expects 1.0.2.
  • .github/workflows/validate.yml: the allowlist gains 86ea824… and 98196a5…, and three local records are expected.
  • tests/test_imported_skill_contracts.py: asserts the new markers and the absence of publisher plan, github-settings/AGENTS.md, before `--apply` , the README-tools allowance and the standing allowlist update. It also checks that both delivery skills still cite `github-settings/config/planning.json`.
  • PROVENANCE.md: lists the new reviewed pair.

How the update reaches the machines

Nothing is published or released by hand. The Claude Code and Codex marketplaces that install atrinik-development track this repository's main branch, so 1.0.2 reaches each machine when its client refreshes that marketplace after the merge.

To get it sooner on a machine, refresh the marketplace that lists this plugin, update atrinik-development from it, and start a new session (claude plugin marketplace update <marketplace> then claude plugin update atrinik-development@<marketplace>; for Codex, codex plugin marketplace upgrade <marketplace>). The installed version should then read 1.0.2.

The owner only needs to merge. The refresh is optional.

Validation

Local, from a fresh clone with the provenance objects fetched the way CI fetches them:

  • python3 -m unittest discover -v: 59 tests OK (Python 3.14), at head after the review fixes
  • python3 -W error -m compileall -q -f tests: clean
  • git diff --check 98196a5: clean
  • I checked that the new governance assertions fail against the old skill text (9 failures) and pass with the new text.
  • The squash-hydration test runs the CI fetch script against a synthetic squash and confirms that the new source commit is restored and validates.

CI runs the same checks on Python 3.11 and 3.13. actionlint is not installed here. The workflow change only edits literals inside the existing Python run block.

Limitations / follow-up

  • After the squash merge, CI on main fetches 86ea824 by SHA from GitHub through this PR's refs/pull/8/head, the same way f723d04 from docs(classic): align LLVM execution guidance #4 is served. Do not rewrite this branch's history up to 86ea824. Any later edit to the governance SKILL.md needs its source revision in the record moved to a commit that contains the final bytes.
  • Merge order: chore: retire the settings publisher, sync and audit github-settings#106 (the retirement PR, still a draft) should merge first so that repository's README.md and AGENTS.md stop describing the publisher. This PR is safe on its own either way: it bans those scripts by name even while they are still in the current tree.
  • Step 6 of the settings redesign adds a read-only settings check to atrinik/github-settings and a guidance paragraph telling agents to run it before and after every settings change. This skill's step 3 bans every bin/ script of that repository, from its current tree too, and tests/test_imported_skill_contracts.py pins the marker "from its current tree, an old checkout or a release". Until this skill changes, the two instructions conflict. The step-6 work must therefore include a PR here that names the check as the one allowed tool (by path, read-only), keeps the ban on the retired scripts, updates that marker test, moves the provenance source revision to the new commit, and bumps the plugin version.
  • The Codex upgrade refresh behaviour for a version bump cannot be confirmed until after the merge.

🤖 Generated with Claude Code

zoeyrose and others added 2 commits November 14, 2026 13:12
The atrinik/github-settings publisher, audit and Project sync are
retired. The governance skill no longer tells agents to run the
publisher plan before --apply or to follow github-settings/AGENTS.md
as a script runbook. It now points at that repository's current README
and AGENTS.md, forbids the old bin/ scripts from its history, and
describes hand changes under the owner's login: only when the task asks,
exported first, re-read live and recorded in the same task.

Correct the PR-only step range (3-5) and bump the plugin to 1.0.2.

Co-Authored-By: Claude <noreply@anthropic.com>
Record the locally authored atrinik-github-governance/SKILL.md update
from baseline 98196a5 to reviewed source fd2cf05, with its MIT license
blob. Each local update path now admits exactly one reviewed
(source, baseline) role pair; CI fetches the two new full commit IDs
and expects three local records. PROVENANCE.md lists the new pair.

Co-Authored-By: Claude <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown

Dependency Review

✅ No vulnerabilities or license issues found.

Scanned Files

None

zoeyrose and others added 2 commits November 14, 2026 13:18
The current atrinik/github-settings tree, README and AGENTS.md still
describe bin/publish and the other retired scripts until that
repository's retirement PR merges. Ban its bin/ scripts by name from the
current tree, an old checkout or a release, and drop the allowance for
tools its README documents.

Workflow changes no longer make Actions allowlist or ruleset edits a
standing step: report the change they need and make it only when the
task asks for it.

Co-Authored-By: Claude <noreply@anthropic.com>
The governance SKILL.md bytes changed in 86ea824, so the local
provenance record, the CI approved-revision allowlist, the offline role
pair and PROVENANCE.md now name 86ea824 as the reviewed source in place
of fd2cf05. The baseline stays 98196a5.

Co-Authored-By: Claude <noreply@anthropic.com>
@zoeyrose

Copy link
Copy Markdown
Member Author

Self-review

Reviewed by fresh-context independent reviewer subagents, given the intent brief.

Round 0 - whole diff at 6a0b294cdd87bd8d31cb69fc47d131538d619982:

  • P2 atrinik-github-governance/SKILL.md:20: step 3 allowed whatever the current atrinik/github-settings README documents, and on main that README still documents the publisher. Fixed in 86ea824: the skill now bans that repository's bin/ scripts by name (with or without --apply, from the current tree, an old checkout or a release), and the "tools its current README documents" allowance is gone. The PR body says chore: retire the settings publisher, sync and audit github-settings#106 should merge first and that this PR is safe either way. Tests assert the new markers.
  • P3 SKILL.md:44: "change policy coherently" made allowlist and ruleset edits a standing step of every workflow change. Fixed in 86ea824: the agent now reports the needed allowlist, ruleset or required-check change and makes it only if the task asks for it. A test asserts the new text.
  • P3 PR body: the body becomes the public squash commit message, and it contained private host paths. Fixed in the PR body (edited with gh api PATCH, no commit): the install section has no host paths, private marketplace names or cache paths.

Round 1 - delta review of the fixes, at 30b30681e0b3846cbfb2008864c41d71cc55c75e:

  • P3 SKILL.md:18: the blanket ban on github-settings bin/ scripts would also forbid the planned step-6 read-only check, and Limitations did not mention it. Addressed in the PR body only, no commit. The ban stays strict on purpose: until #106 merges, a "tools in README" allowance would let a stale README reopen the retired scripts. The intent brief now says the check is not allowed yet. A Limitations / follow-up item says the step-6 work must include a PR here that names the check by path, keeps the ban, updates the pinned marker test and bumps the version.

Coverage note. Round 1 reviewed the code at the current head 30b30681e0b3846cbfb2008864c41d71cc55c75e. Its only finding was answered by editing the PR body. The code has not changed since round 1, but that last body edit was not delta-reviewed, and no review round has come back with zero findings. I have not claimed a clean final review.

@zoeyrose
zoeyrose marked this pull request as ready for review November 14, 2026 19:23
@zoeyrose zoeyrose self-assigned this Nov 14, 2026
@zoeyrose
zoeyrose requested a review from a team November 14, 2026 19:23
@zoeyrose
zoeyrose merged commit c41b3fb into main Nov 14, 2026
12 checks passed
@zoeyrose
zoeyrose deleted the fix/retired-settings-tooling-guidance branch November 14, 2026 19:30
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