Epic: ACT rule board and per-rule AGWG publish PRs

[WilcoFiers]

What we are building

A bot-owned inventory: one GitHub issue per rule in a new act-rules/act-board repo, shown in a table Project. A weekly (and on-demand) Action recomputes state from act-rules.github.io + w3c/wcag-act-rules and updates issues/fields only when the snapshot changed.

Humans comment on issues; they do not edit bodies or Status. Review “in flight” is an open per-rule PR on w3c/wcag-act-rules that changes content/rules/{id}/index.md.

flowchart LR
  cg[act-rules.github.io]
  wai[w3c/wcag-act-rules]
  tools[act-tools classifier]
  board[act-board issues + Project]
  cg --> tools
  wai --> tools
  tools --> board
  board -->|"later: open PR"| wai

Loading

Out of this epic: coverage-drop @mentions (tracked as a later child), a second Project view of CG blocker issues, the giant markdown report as a human UI.

Sub-issues are labeled HITL (needs a person: org settings, tokens, repo/project creation, changelog confirmation) or AFK (an agent can implement).

Status model (Project single-select)

Apply in this order:

1. Deprecated — rule deprecated in CG frontmatter: close the act-board issue and drop it from the default table. (Project built-in “item closed → Done” workflows must stay off so closed issues do not land in Approved, current.)
2. In review — open w3c/wcag-act-rules PR touching content/rules/{id}/index.md.
3. Blocked by issue — ≥1 open CG issue matched to the rule with label Blocker.
4. Awaiting implementation — no tool with consistency: "complete" in w3c/wcag-act-rules _data/wcag-act-rules/implementations/*.json (tool names/metadata from act-implementations.yml).
5. Approved, current — WAI snapshot (index.md + isoDate in rule-versions.yml) and no commits after that date on the rule file or its glossary terms.
6. Approved, unpublished changes — approved snapshot, and commits after approval.
7. Proposed, reviewable — not approved, complete impl, no blockers.

Open non-blocker CG issues never change status. They still appear in the issue body.

Commit split (both shown): count of commits that touched _rules/{id}.md vs commits that only touched that rule’s glossary paths. Expose two numbers plus the full list in the body. That list is board raw material, not the published WAI changelog.

Issue contract (act-board)

• Title key: [674b10] Role attribute has valid value (id is the upsert key).
• Body: fully generated. First lines: a short “generated by a bot; do not edit” note, then changelog, non-blocker CG issue links, complete implementations, links to proposed/approved WAI pages and the CG rule file.
• Skip API writes when title, body, Status, custom fields, and sub-issue set are unchanged.
• Blockers are cross-repo sub-issues, not copies. Each CG issue with label Blocker that matches the rule is added as a sub-issue of the act-board parent (addSubIssue from act-board to act-rules.github.io). Do not open mirror tickets. When the label is removed or the CG issue closes, remove the sub-issue link.
• GitHub allows one parent per issue. If a blocker matches several rules, attach it under one parent only (lowest rule id) and still mention it in every matching rule’s body so Status can stay Blocked by issue on all of them.

Suggested Project fields: Status, type (atomic / composed / composite), impl count, blocker count, open issue count, rule-commits, definition-commits, last approved, last updated, review PR URL.

Machine snapshot: commit data/snapshot.json (the classifier row array) on each real change so later tools do not scrape issue HTML.

Engine (act-tools)

Land and extend #54 rather than forking bucket logic.

Today the approval-report uses four buckets and treats any post-approval commit as “behind.” Change it to emit the seven Status values, split commit counts, list matched issues/blockers, and optional reviewPrUrl from GitHub.

CLI: JSON (required for the board); keep markdown only as a debug dump if cheap.

Need GitHub: list open issues on the CG repo (already in #54), list open PRs on w3c/wcag-act-rules filtered by content/rules/{id}/index.md.

Board sync

New repo act-rules/act-board: README, Project, workflow (weekly + workflow_dispatch). Job checks out (or npm-installs) act-tools, clones CG + wcag-act-rules, runs the classifier, upserts issues, sets Project fields via Projects v2 GraphQL.

Auth: GitHub App or PAT with issues write on both act-board and act-rules.github.io (to add/remove cross-repo sub-issues), project write on act-board, and read on wcag-act-rules. W3C write comes later for opening PRs.

Per-rule publish PRs (after the board is live)

Today: CG workflow approve-rule.yml + approve-rule.mjs. It runs rule-transform without --proposed (writes index.md), then asserts the rule is absent from rule-versions.yml and does not archive a previous snapshot. That matches first-time approval only.

The WAI page changelog (rule-versions.yml changes:, rendered on the rule) is confirmed, user-facing prose. It is not classifier git subjects. Do not generate it from the weekly bot.

Split:

• AFK script (AFK: Extend approve-rule for re-approval, one branch per rule #64): first-time approval stays as today. Re-approval archives index.md → {previousIsoDate}.md, writes new index.md, keeps examples.json approved, records changes: from an explicit input (repeated --change or a YAML file). Refuse an update with an empty changelog. One branch per rule.
• HITL skill (HITL: Skill to draft WAI changelog and run approve-rule #73): drafts 2–6 bullets in existing WAI voice from the proposed-vs-approved diff (plus snapshot/git as context), plus a short AGWG PR body. Person confirms before the script runs. First-time approval skips changelog.
• AFK dispatch (AFK: workflow_dispatch to open a single-rule AGWG publish PR #67): workflow_dispatch with a single ruleId and that confirmed changelog; opens one PR on w3c/wcag-act-rules. No batching. Weekly sync does not call this.

Detecting those PRs (#66) is what sets In review; merge → new isoDate → Approved, current (or unpublished if more CG commits landed); close without merge → back to proposed/unpublished.

Process note

CG Blocker label is the only human switch for Blocked by issue. Do not edit generated act-board issue bodies. Closing or unlabelling the CG issue is how a sub-issue falls off the parent.

Children

• HITL: Create act-board repo, table Project, fields, and bot secrets — HITL: Create act-board repo, table Project, fields, and bot secrets #61
• AFK: Classifier JSON, seven statuses, and split commit counts — AFK: Classifier JSON, seven statuses, and split commit counts #62
• AFK: Generate act-board issue bodies and upsert by rule id — AFK: Generate act-board issue bodies and upsert by rule id #63
• AFK: Weekly Action to sync Project fields and snapshot.json — AFK: Weekly Action to sync Project fields and snapshot.json #65
• AFK: Map open wcag-act-rules PRs to In review — AFK: Map open wcag-act-rules PRs to In review #66
• AFK: Extend approve-rule for re-approval, one branch per rule — AFK: Extend approve-rule for re-approval, one branch per rule #64
• HITL: Skill to draft WAI changelog and run approve-rule — HITL: Skill to draft WAI changelog and run approve-rule #73
• AFK: workflow_dispatch to open a single-rule AGWG publish PR — AFK: workflow_dispatch to open a single-rule AGWG publish PR #67
• Later: Notify implementers when ACT rule coverage drops — Later: Notify implementers when ACT rule coverage drops #68