Add a skill for publishing one ACT rule

.agents/skills/publish-act-rule/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: publish-act-rule
+description: >-
+  Drafts the WAI changelog and an AGWG pull-request body for a single ACT
+  rule, runs approve-rule after the user confirms, then opens one draft pull
+  request. Use when the user asks to approve a rule, publish a rule to WAI or
+  AGWG, draft a WAI changelog, or re-approve a rule with unpublished changes.
+---
+
+# Publish one ACT rule to WAI
+
+One `ruleId` per run. The rule is either **Approved, unpublished changes** (re-approval) or first-time **Proposed, reviewable**.
+
+## Out of scope
+
+Weekly board sync, publishing more than one rule, opening a batch of AGWG pull requests, and writing `changes:` from git commit subjects alone. `workflow_dispatch` in `.github/workflows/approve-rule.yml` does not accept a changelog yet ([act-tools#67](https://github.com/act-rules/act-tools/issues/67)). After confirmation, run the local script. Issue #67 can replace that local run later.
+
+## Workflow
+
+1. **Resolve the rule.** `ruleId` is six characters. Find `_rules/*-{ruleId}.md` in this repo and read `name` from its frontmatter. If the user names several ids, ask which single rule to publish and stop.
+
+2. **Gather inputs.** Follow `reference.md` (Inputs). Use a sibling `wcag-act-rules` clone and, when present, a sibling act-board snapshot. Read WAI pages from `origin/main`, not from a working tree and not from `./wcag-act-rules-tmp/`. If `snapshot.json` is missing, `[]`, or has no row for this id, infer first-time versus re-approval from `rule-versions.yml` on `origin/main` and say that board status was unavailable.
+
+3. **Read the content diff.** Follow `reference.md` (Changelog diff). Render the current `_rules/` file with `rule-transform` and diff that `index.md` against `index.md` on `origin/main`. That diff is the changelog source. Snapshot `changes[].subject` values are context only. When the diff and a subject disagree, follow the diff. If `proposed.md` is missing on `origin/main`, stop: `approve-rule` reads it for `last_modified` before it generates pages.
+
+4. **Draft.** Re-approval: a YAML list of strings in existing WAI voice (typically 2–6), plus a one-paragraph AGWG body that separates substantive from editorial. First-time (no `file: index.md` version in `rule-versions.yml` on `origin/main`): omit `changes:`; the paragraph states that this is the first approval. Voice and published examples are in `examples.md`.
+
+5. **Stop for confirmation.** Present the draft with the template in `reference.md` (Confirm gate), including the exact command. Wait until the user accepts that text or supplies a replacement. Questions and vague tweaks are not confirmation: revise and stop again. Do not run `approve-rule` before an explicit accept.
+
+6. **Run the script only after confirmation.** First-time: invoke with no `--change` and no `--changesFile`. Re-approval: pass the accepted non-empty list via repeated `--change` and/or `--changesFile`. Refuse an empty list before invoking. Preconditions and the push side effect are in `reference.md` (Run approve-rule).
+
+7. **Open one draft pull request after the branch is on `origin`.** Follow `reference.md` (Draft pull request), including the title. A re-approval is `Update approved rule: {name} ({ruleId})`. A first approval is `Approve rule: {name} ({ruleId})`. If the script did not push, stop and report that. Do not open a second pull request for the same branch.
+
+## Further detail
+
+See `reference.md` for inputs, the confirm template, editorial versus substantive, the CLI contract, and the draft pull request body. See `examples.md` for published `rule-versions.yml` bullets and a worked draft.

.agents/skills/publish-act-rule/examples.md

@@ -0,0 +1,131 @@
+# Examples: WAI changelog voice
+
+Bullets below are copied from published `changes:` entries in `wcag-act-rules` `_data/wcag-act-rules/rule-versions.yml`. They show the voice. They are not a draft for a new diff.
+
+## Published bullets
+
+**de46e4**, archived `2022-06-23` (three effects, including a definition change as it hits this rule):
+
+- Account for whitespace in the applicability
+- Add assumption about text containing human language
+- Account for focus redirects in "focusable" definition
+
+**e086e5**, current `index.md` (substantive spec and examples, plus editorial background):
+
+- Update to reference ARIA 1.2
+- Remove outdated accessibility support info
+- Editorial clarifications of the background
+- New examples using menuitemcheckbox role
+
+**e086e5**, archived `2022-06-23` (definition-only effects on this rule; YAML wraps the long line, it is one string):
+
+- Account for focus redirects in "focusable" definition
+- Let hidden attribute be handled by display:none in "programmatically hidden" definition
+
+**9e45ec** and **24afc2**, current `index.md`:
+
+- Update the rule's description
+- Ignore style attributes which do not actually impact text
+- Add assumption on text nodes being human language
+
+**46ca7f**, current `index.md` (a single effect is enough):
+
+- Update to reference ARIA 1.2
+
+**2779a5**, current `index.md`:
+
+- Replace Web Page definition with HTML-specific definition
+- Add higher-level protocol assumption
+
+**akn7bn**, current `index.md`:
+
+- Added inapplicable example 5 and 6
+
+**m6b1q3**, current `index.md` (editorial section only):
+
+- Updated accessibility support section
+
+**9e45ec**, archived `2022-06-23`:
+
+- Simplify accessibility support paragraph
+
+**73f2c2**, current `index.md`:
+
+- Update to allow webauthn token
+- Add several more examples
+
+## What to do with commit subjects
+
+Snapshot `changes[].subject` might look like:
+
+- `prettier`
+- `Update last_modified`
+- `fix focusable (#1234)`
+- `glossary: programmatically hidden`
+
+The diff of the rendered approved page against `index.md` on `main` for the same history shows whitespace handling in Applicability, a new human-language assumption, and inlined glossary edits for "focusable" and "programmatically hidden".
+
+Publish the effects, collapsed:
+
+```yaml
+- Account for whitespace in the applicability
+- Add assumption about text containing human language
+- Account for focus redirects in "focusable" definition
+- Let hidden attribute be handled by display:none in "programmatically hidden" definition
+```
+
+Leave `prettier` and `last_modified` out. A definition commit that does not change the rendered approved page versus `index.md` on `main` does not get a bullet.
+
+Labels for the confirm message (they stay out of the YAML):
+
+| Bullet                                                                                  | Class                                                                                                                                                |
+| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Account for whitespace in the applicability                                             | substantive                                                                                                                                          |
+| Add assumption about text containing human language                                     | editorial                                                                                                                                            |
+| Account for focus redirects in "focusable" definition                                   | from the page diff: substantive if Applicability, Expectations, or example outcomes change; editorial if only the inlined definition wording changes |
+| Let hidden attribute be handled by display:none in "programmatically hidden" definition | same rule as the focusable bullet                                                                                                                    |
+
+Paragraph for that re-approval, if the definition edits change how the rule treats targets:
+
+> This pull request updates the approved version of rule abcd12 (Example rule name). Substantive changes account for whitespace in the applicability and for focus redirects in the "focusable" definition, and let the hidden attribute be handled by display:none in the "programmatically hidden" definition. Editorial changes add an assumption that text contains human language.
+
+`abcd12` and "Example rule name" are placeholders. Use the real id and frontmatter `name`.
+
+## First-time approval
+
+No `index.md` in `rule-versions.yml` for `abcd12`. Do not draft `changes:`, even if the Community Group history is long.
+
+Paragraph:
+
+> This pull request approves rule abcd12 (Example rule name) for the first time. There is no previous approved snapshot, so the version list has no changelog.
+
+Command after acceptance, from `act-rules.github.io`:
+
+```bash
+npx zx .github/scripts/approve-rule.mjs --ruleId abcd12 --branch approve-abcd12
+```
+
+## Re-approval command
+
+After the user accepts the four bullets above, write them to `/tmp/abcd12-changes.yml` as a YAML list and run:
+
+```bash
+npx zx .github/scripts/approve-rule.mjs \
+  --ruleId abcd12 \
+  --branch approve-abcd12 \
+  --changesFile /tmp/abcd12-changes.yml
+```
+
+Equivalent flag form:
+
+```bash
+npx zx .github/scripts/approve-rule.mjs \
+  --ruleId abcd12 \
+  --branch approve-abcd12 \
+  --change "Account for whitespace in the applicability" \
+  --change "Add assumption about text containing human language" \
+  --change "Account for focus redirects in \"focusable\" definition" \
+  --change "Let hidden attribute be handled by display:none in \"programmatically hidden\" definition"
+```
+
+These examples are documentation. Do not run them while reading the skill, and do not run them against a real rule until the confirm gate for that rule has been accepted. After that command pushes the branch, the draft pull request body is the accepted paragraph plus `## Changes` and `## Preview`, as specified in `reference.md` (Draft pull request).