fix(a11y): 수동 접근성 기록이 릴리스 태그로 서명되고 WCAG 2.2 칸을 갖는다

수동 접근성 기록 검사에 구멍이 둘 있다.
- FE-GATE-028(`review:a11y-manual`)은 기록끼리 Release ID가 같은지만 본다
  (05-01). 후보를 받는 입력이 없어, 첫 release에 세 기록을 서명한 뒤 화면을
  바꾸고 기록을 그대로 둔 채 다음 release를 돌아도 통과한다. checklist의
  "release 후보마다 한 번"이 지켜지지 않는다(결함 패턴 G7).
- 제품은 WCAG 2.2 AA를 약속하는데 기록 양식은 M1~M7과 스크린 리더뿐이다
  (05-05의 남은 것). axe에 규칙이 없는 2.4.11 포커스 가림과 일부만 보는 2.5.8
  목표 크기를 볼 칸이 없다.

고른 방법:
- 결정(2026-11-13, r9-fe·w2-fe-2: 후보 ID는 릴리스 태그)대로
  `scripts/verify-a11y-manual.ts`가 env `RELEASE_TAG`를 읽고, 각 기록의
  `Release ID`가 그 태그와 같지 않으면 실패한다. 태그가 비면 비교할 것이 없으니
  모두 실패한다(fail-closed). release job은 이미 `RELEASE_TAG`를 넘기고
  FE-GATE-028이 그것을 요구한다(main `000b5a35`). 규칙은
  `releaseTagFailures`(`scripts/lib/manual-a11y-evidence.ts`)에 둔다.
- 결정 R9-D9(2026-11-12, 총괄)대로 기록 양식에 `M8 Focus not obscured`
  (2.4.11)와 `M9 Target size`(2.5.8)를 더한다: 검사기의 필드 목록, checklist,
  템플릿 기록 셋, `create:feature`가 만드는 기록. checklist의 `Release ID` 예는
  "release tag"로 바꿨다.
- 버린 대안: workflow의 `RELEASE_ID`와 대조(run마다 달라 사람이 미리 적을 수
  없다), 칸 없이 태그만 더하기(2.2 AA 일부를 아무도 보지 않는다).

위험·한계: 다운스트림의 기존 route 기록에는 M8·M9가 없어 다음 동기화 뒤
FE-GATE-009 형식 검사가 그 필드 이름을 대며 실패한다. 기록마다
`M8 Focus not obscured: pending`, `M9 Target size: pending` 두 줄을 더하면 된다.
서명한 기록의 `Release ID`는 다음 release부터 태그(예 `v1.4.0`)로 적는다.

검증: `tests/unit/manual-a11y-evidence.test.ts`(M8·M9가 빠진 기록 거절, 태그
같음·다름·빔, `review:a11y-manual`을 실제로 띄워 태그로 통과·다음 태그와 빈
태그로 실패)가 고치기 전 코드에서 실패하고 고친 뒤 통과한다(desktop, PR 본문).

Refs: 1112/05-01, 1112/05-05
This commit is contained in:
DongHyeonka
2026-11-13 18:45:16 +09:00
parent ee95573f9b
commit aa4bddac36
11 changed files with 144 additions and 17 deletions
+2
View File
@@ -1620,6 +1620,8 @@ M4 Modal focus: pending
M5 Error association: pending
M6 Color signal: pending
M7 Reduced motion: pending
M8 Focus not obscured: pending
M9 Target size: pending
Screen reader: pending
Notes: Human review pending. ${GENERATED}
`;
+22
View File
@@ -12,6 +12,10 @@ const REVIEW_FIELDS = Object.freeze([
"M5 Error association",
"M6 Color signal",
"M7 Reduced motion",
// 1112/05-05. WCAG 2.2 AA criteria axe has no rule for (focus not obscured
// 2.4.11) or covers only in part (target size 2.5.8).
"M8 Focus not obscured",
"M9 Target size",
"Screen reader",
]);
@@ -98,3 +102,21 @@ export function validateManualA11yEvidence(content: string) {
passed: failures.length === 0,
});
}
/**
* 1112/05-01. A signed record is evidence for one release only: the release
* tag the release job is building (`RELEASE_TAG`, e.g. `v1.4.0`). A record
* signed for an earlier tag does not pass a later one. With no tag there is
* nothing to compare with, so every record fails (fail-closed).
*/
export function releaseTagFailures(
releaseTag: string | undefined,
releaseId: string | null | undefined,
): string[] {
const tag = releaseTag?.trim() ?? "";
if (tag === "") return ["no release tag to compare the Release ID with (RELEASE_TAG is empty)"];
if (releaseId !== tag) {
return [`Release ID ${releaseId ? `"${releaseId}"` : "(empty)"} is not the release tag "${tag}"`];
}
return [];
}
+11 -5
View File
@@ -3,6 +3,7 @@ import { mkdir, readFile } from "node:fs/promises";
import { manualA11yReportArtifactSchema } from "./contracts/release-artifacts.ts";
import {
MANUAL_A11Y_ROUTE_IDS,
releaseTagFailures,
validateManualA11yEvidence,
validateManualA11yRecordFormat,
} from "./lib/manual-a11y-evidence.ts";
@@ -39,15 +40,20 @@ if (process.argv.includes("--format-only")) {
process.exit(0);
}
// 1112/05-01. The release job passes the tag it is releasing (FE-GATE-028
// declares RELEASE_TAG as required, so run-ci-gate refuses a run without it);
// every record must be signed for that tag.
const releaseTag = process.env.RELEASE_TAG;
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `docs/accessibility/route-reviews/${routeId}.md`;
const evidence = await readFile(path, "utf8");
const validation = validateManualA11yEvidence(evidence);
const failures =
validation.fields["Route ID"] === routeId
? validation.failures
: Object.freeze([...validation.failures, "Route ID mismatch"]);
const failures = Object.freeze([
...validation.failures,
...(validation.fields["Route ID"] === routeId ? [] : ["Route ID mismatch"]),
...releaseTagFailures(releaseTag, validation.fields["Release ID"]),
]);
results.push({
routeId,
path,
@@ -55,7 +61,7 @@ for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
reviewedAt: validation.fields["Reviewed at"] ?? null,
releaseId: validation.fields["Release ID"] ?? null,
failures,
passed: validation.passed && failures.length === 0,
passed: failures.length === 0,
});
}
const releaseIds = new Set(