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

.github/workflows/ci.yml

@@ -260,6 +260,68 @@ jobs:
           Write-Host "::error::CheckForUpdates outcomes: v1 updatesAvailable '$($env:UNCHANGED)' (expected false), v2 '$($env:MOVED)' (expected true), update without token '$($env:NOTOKEN)' (expected failure/token)"
           exit 1
 
+  # The change workflow on a copy of valid-minimal: no token, nothing pushed. The token guard runs after the local
+  # plan, so a valid change fails on the token while a no-op and an invalid id need none.
+  changerule-action:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Prepare the fixture
+        id: fixture
+        shell: pwsh
+        run: |
+          . ./tests/Helpers/RepoFixture.ps1
+          $org = New-FixtureRepo -Name 'valid-minimal' -Destination (Join-Path $env:RUNNER_TEMP 'change-org')
+          Add-Content -LiteralPath $env:GITHUB_OUTPUT -Value "org=$org"
+
+      - name: Change AA0001 to None without the token (must fail)
+        id: notoken
+        continue-on-error: true
+        uses: ./actions/ChangeRule
+        with:
+          repositoryRoot: ${{ steps.fixture.outputs.org }}
+          ruleId: AA0001
+          action: None
+          levels: '*'
+          stages: '*'
+
+      # valid-minimal already has AA0072 Info for every level and stage; an empty justification keeps its text.
+      - name: No-op change
+        id: noop
+        uses: ./actions/ChangeRule
+        with:
+          repositoryRoot: ${{ steps.fixture.outputs.org }}
+          ruleId: AA0072
+          action: Info
+          levels: '*'
+          stages: '*'
+
+      - name: Invalid id (must fail)
+        id: invalid
+        continue-on-error: true
+        uses: ./actions/ChangeRule
+        with:
+          repositoryRoot: ${{ steps.fixture.outputs.org }}
+          ruleId: LC9999
+          action: Warning
+
+      # The outputs name the outcome, so a crash or another error does not pass.
+      - name: Require the three outcomes
+        if: steps.notoken.outcome != 'failure' || steps.notoken.outputs.failure != 'token' || steps.noop.outputs.noop != 'true' || steps.invalid.outcome != 'failure' || steps.invalid.outputs.failure != 'validation'
+        shell: pwsh
+        env:
+          NOTOKEN: ${{ steps.notoken.outcome }}/${{ steps.notoken.outputs.failure }}
+          NOOP: ${{ steps.noop.outputs.noop }}
+          INVALID: ${{ steps.invalid.outcome }}/${{ steps.invalid.outputs.failure }}
+        run: |
+          Write-Host "::error::ChangeRule outcomes: without token '$($env:NOTOKEN)' (expected failure/token), no-op '$($env:NOOP)' (expected true), invalid id '$($env:INVALID)' (expected failure/validation)"
+          exit 1
+
   # The scan against the real packages on nuget.org (the unit suites use stub packages). Every run is a dry run: no
   # token, nothing pushed. nuget.org moves, so the checks are lower bounds and the log prints the numbers.
   scan-action:

README.md

@@ -19,15 +19,15 @@ The engine behind [ALCops/rulebook](https://github.com/ALCops/rulebook): the com
 
 | Path | Content | Status |
 |---|---|---|
-| `actions/<Name>/action.yaml` | Composite actions, each running a PowerShell 7 entry script on `ubuntu-latest`: `Validate` (checks, effective diff, update check), `Publish` (gate, stage, deploy, verify), `CheckForUpdates` (update from the template), `ScanDiagnostics` (the daily diagnostic scan). | `Validate` (WP03), `Publish` (WP05), `CheckForUpdates` (WP07) and `ScanDiagnostics` (WP08) written; `ChangeRule` planned (WP09) |
-| `modules/Rulebook.*.psm1` | PowerShell modules shared by the actions, each with a `.psd1` manifest: `Rulebook.Generate` (level chain + stage deltas + twins setting + overrides + quarantine to sparse flat endpoints, effective diff), `Rulebook.Validate` (checks C1 to C16), `Rulebook.Template` (level, stage, twins, catalog and skeleton files of `template/` from `docs/rulebook/`), `Rulebook.Publish` (staging, Pages deploy, reachability), `Rulebook.Update` and `Rulebook.GitHub` (the update and the GitHub plumbing), for the scan `Rulebook.NuGet`, `Rulebook.Extract`, `Rulebook.Catalog`, `Rulebook.Quarantine` and `Rulebook.Scan`, and `Rulebook.Action` (the helpers every action entry script shares: annotations, the failure kind, the job summary and `GITHUB_OUTPUT`). | written (WP03 to WP09) |
-| `template/` | Source of the template content that a deploy workflow copies into `ALCops/rulebook`, pinning action references from `@main` to `@v1`. Its `base/`, `stages/` and `rulesets/` are generated from `docs/rulebook/`. | written (WP03 to WP08), 43 files: settings, the workflows `Validate.yaml`, `Publish.yaml`, `UpdateRulebookSystemFiles.yaml` and `ScanDiagnostics.yaml`, the README files, empty overrides and quarantine files, and the 32 generated files; the other workflows come with their work packages, the deploy with WP13 |
+| `actions/<Name>/action.yaml` | Composite actions, each running a PowerShell 7 entry script on `ubuntu-latest`: `Validate` (checks, effective diff, update check), `Publish` (gate, stage, deploy, verify), `CheckForUpdates` (update from the template), `ScanDiagnostics` (the daily diagnostic scan), `ChangeRule` (one override entry through a form, as a pull request). | `Validate` (WP03), `Publish` (WP05), `CheckForUpdates` (WP07), `ScanDiagnostics` (WP08) and `ChangeRule` (WP09) written |
+| `modules/Rulebook.*.psm1` | PowerShell modules shared by the actions, each with a `.psd1` manifest: `Rulebook.Generate` (level chain + stage deltas + twins setting + overrides + quarantine to sparse flat endpoints, effective diff), `Rulebook.Validate` (checks C1 to C16), `Rulebook.Template` (level, stage, twins, catalog and skeleton files of `template/` from `docs/rulebook/`), `Rulebook.Publish` (staging, Pages deploy, reachability), `Rulebook.Update` and `Rulebook.GitHub` (the update and the GitHub plumbing), for the scan `Rulebook.NuGet`, `Rulebook.Extract`, `Rulebook.Catalog`, `Rulebook.Quarantine` and `Rulebook.Scan`, `Rulebook.Edit` (overrides.json and the change set of the ChangeRule action) and `Rulebook.Action` (the helpers every action entry script shares: annotations, the failure kind, the job summary and `GITHUB_OUTPUT`). | written (WP03 to WP09) |
+| `template/` | Source of the template content that a deploy workflow copies into `ALCops/rulebook`, pinning action references from `@main` to `@v1`. Its `base/`, `stages/` and `rulesets/` are generated from `docs/rulebook/`. | written (WP03 to WP09), 44 files: settings, the workflows `Validate.yaml`, `Publish.yaml`, `UpdateRulebookSystemFiles.yaml`, `ScanDiagnostics.yaml` and `ChangeRule.yaml`, the README files, empty overrides and quarantine files, and the 32 generated files; the other workflows come with their work packages, the deploy with WP13 |
 | `schemas/` | JSON schemas for every file in an organization rulebook repository (ruleset profiles, overrides, quarantine, twins, catalog, scan state, settings), served from the `v1` branch over raw URLs, which go live with WP13 ([#15](https://github.com/ALCops/rulebook-engine/issues/15)) and return 404 until then; the tests use the local files. See [docs/reference/naming.md](docs/reference/naming.md). | written (WP02) |
-| `tests/` | Pester 6 suites, one per module and action, with fixtures under `tests/fixtures/`: the schema suite and its fixtures under `tests/fixtures/schemas/`; the Generate, Validate and Validate action suites with organization rulebook fixtures under `tests/fixtures/repos/` and helpers in `tests/Helpers/`. | a suite per module and action (WP00 to WP08); the scan suites build stub analyzer packages from `tests/fixtures/stub-analyzers/` at test time |
+| `tests/` | Pester 6 suites, one per module and action, with fixtures under `tests/fixtures/`: the schema suite and its fixtures under `tests/fixtures/schemas/`; the Generate, Validate and Validate action suites with organization rulebook fixtures under `tests/fixtures/repos/` and helpers in `tests/Helpers/`. | a suite per module and action (WP00 to WP09); the scan suites build stub analyzer packages from `tests/fixtures/stub-analyzers/` at test time |
 | `docs/` | Architecture, decision records (`adr/`), references, and `docs/rulebook/` with the level content (inventory, matrix, composition spec). | written |
 | `tools/rulebook/` | PowerShell scripts that extract the inventory from the analyzer sources, build the matrix (ladders, stage columns, twin pairs, counts) and verify it (`Extract-Inventory.ps1`, `Build-Matrix.ps1`, `Test-Rulebook.ps1`). They import `Rulebook.Generate` for the diagnostic sort key and build portable paths; CI runs `Test-Rulebook.ps1`. `Build-Template.ps1` regenerates `template/` from `docs/rulebook/`. | written |
 | `scripts/` | User-facing scripts that an AL project downloads from the engine and runs, self-contained (PowerShell 7, no engine module): `Get-RulebookSkeletons.ps1` reads `<baseUrl>/rulebook.json` and downloads the published skeletons of one level into `.rulebook/`, one file per stage. Linked from the index page of every published rulebook. | written (WP06) |
-| `.github/workflows/` | `ci.yml`: the job `test` (PSScriptAnalyzer, the matrix checks V1 to V14, Pester) and one job per action, `validate-action`, `publish-action`, `update-action` and `scan-action` (dry runs against nuget.org); the deploy workflow comes with WP13. | CI written (WP00); deploy planned (WP13) |
+| `.github/workflows/` | `ci.yml`: the job `test` (PSScriptAnalyzer, the matrix checks V1 to V14, Pester) and one job per action, `validate-action`, `publish-action`, `update-action`, `scan-action` (dry runs against nuget.org) and `changerule-action`; the deploy workflow comes with WP13. | CI written (WP00); deploy planned (WP13) |
 | `CONTRIBUTING.md` | Conventions, running the checks locally, CI, branches, repository settings and pull request rules. | written |
 
 ## 2. Relation to the template