WP09: ChangeRule workflow, Rulebook.Edit change-set engine and the ChangeRule action

[Arthurvdv]

Summary

• New module modules/Rulebook.Edit (the change-set engine of D32): overrides.json I/O in the template layout (byte-identical round trip; comments and trailing commas read, a date-like justification stays text), Set-RulebookOverride / Remove-RulebookOverride (one entry per selector set, replaced in place by order-insensitive selector equality; duplicates collapse into the effective entry at its position; a remove miss lists the id's entries), Test-RulebookChangeSet, Invoke-RulebookChangeSet (all or nothing on a candidate copy, never the repository; one row per matching endpoint with provenance; the no-op rule of D48, dead new entries dropped also in multi-item sets), the title, table, pull request body and job summary (the git-based effective diff in the summary only), and Publish-RulebookChange (change-rule/<ruleId>/<yyMMddHHmmss>, base-moved guard, direct commit with the pull-request fallback).
• New action actions/ChangeRule: a one-item client of the engine. The token guard runs after the local plan, so an invalid id or a no-op needs no secret; the token is exchanged and masked before any request. Outputs result (pull-request, direct-commit, no-op), noop, changedEndpoints, pullRequestUrl, branch, failure.
• New template workflow template/.github/workflows/ChangeRule.yaml: inputs ruleId, action (incl. Remove), levels, stages, justification; no directCommit input, landing follows commitOptions.createPullRequest (D47); contents: read; choice lists rewritten by the update (D30), byte-identical with the shipped settings. Template now 44 files, 12 hand-written. The fixture workflows rename id to ruleId.
• CI job changerule-action on a copy of valid-minimal: token failure, no-op, invalid id, and a guard on the three outcomes.
• Tests: Rulebook.Edit.Tests.ps1 (61), ChangeRule.Action.Tests.ps1 (44), the shipped-workflow rewrite case in the Update suite, the template file list.
• Docs: docs/reference/change-mechanics.md (the live-run section follows the E2E), ADRs D47 and D48, ARCHITECTURE 7.5/7.6 and the new 5.8, naming, template content, effective diff, update mechanics, README, template README, CONTRIBUTING (incl. the ruleset JSON with changerule-action).

Decisions

• D47: Change Rule follows commitOptions.createPullRequest on every run and has no directCommit input; a refused direct push falls back to the pull request.
• D48: a change that alters no endpoint is reported and never written (an unchanged entry, or a dead new entry that only repeats what the base, a stage, a broader entry or the twins setting gives); a partial change is written with the full table; a justification-only edit is written; a remove miss is a validation error.
• An empty justification keeps the entry's existing text (Arthur, 2026-10-08); only a non-empty one replaces it, clearing one is a hand edit.
• Shared helper module for the action entry scripts (annotations, summary, outputs) #58 (the shared action helper module) was pulled forward into this work package and merged as Share the action helpers in a Rulebook.Action module (#58) #73; Settings key to turn the Validate template update check off #67 (update.check) as Let update.check in the settings turn the Validate update check off (#67) #74.

Verification: Pester 1601 tests (1600 passed, 1 skipped: the Actions-only smoke test), PSScriptAnalyzer clean, Test-Rulebook V1 to V14 clean, Build-Template -WhatIf current.

Review: three Sonnet rounds at effort high. Round 1: two must-fix (dead new entries were written; the empty-justification rule never ran because a [string] parameter turns $null into '') plus the empty-selector binding error, single-line justification in body and summary, the no-changes result mapped to no-op, the base-guard warning, an unreadable candidate as a validation failure, one entry per selector set, and no GITHUB_TOKEN for the action. Round 2: one must-fix (the summary lost its tables for an empty effective diff, an if expression unrolled @() to $null) plus deduplicated as its own outcome, the row-based no-op notice, dead entries dropped in multi-item sets, empty changedEndpoints for a no-op, repeated slugs kept once, and the "given but not stored" justification line. Round 3: one must-fix (collapsing duplicates kept the first position and could flip precedence on a specificity tie; the survivor now takes the effective, last position) plus rows of dead entries computed against the final state, a row-aware no-op sentence, the summary assertion at action level, ADR 0048 wording, and comments and trailing commas in overrides.json. Not applied: the settings step hard-fails on an invalid ghTokenWorkflowSecretName before the action runs (the same as the Update and Scan workflows; consistency wins); the concurrency queue replacing a waiting run (documented in change-mechanics section 9); the Validate default flip (intended, #74); a tag as ref_name on a direct commit (the form is dispatched from a branch); the multi-item no-op notice naming the first item only (WP15); the quadratic body rebuild, the duplicated secret-name regex and other performance notes.

Live run: all eleven E2E steps and the refused-push fallback observed as designed on Arthurvdv/rulebook-e2e-changerule; the table with run ids and PR links is in docs/reference/change-mechanics.md section 11. Close-out with the acceptance-criteria evidence and the deviations: #11 (comment)

User docs: ALCops/rulebook#6 (merge after this pull request).

Spin-off: #75

Closes #11

🤖 Generated with Claude Code