ci: move the signed manual a11y review to release gate FE-GATE-028 (08-06)

The signed review is per release candidate, so the merge gate could never pass.
FE-GATE-009 now checks only the record format; the checked-in records are
source-controlled evidence, not command output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:07:53 +09:00
co-authored by Claude Opus 5.5
parent 926f448fce
commit 7298275271
16 changed files with 206 additions and 61 deletions
+1
View File
@@ -93,6 +93,7 @@ jobs:
- { gate: FE-GATE-014, name: config-compatibility, browser: false }
- { gate: FE-GATE-019, name: hosting-header, browser: false }
- { gate: FE-GATE-026, name: lab-performance, browser: true }
- { gate: FE-GATE-028, name: manual-accessibility-review, browser: false }
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
+6 -4
View File
@@ -152,13 +152,15 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit
Two gates intentionally need external evidence:
- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
keyboard/focus/screen-reader review for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
`EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`, `NOT_FOUND`,
`REFERENCE_RESOURCE_LIST`, `REFERENCE_RESOURCE_DETAIL`,
`REFERENCE_RESOURCE_FORM` and `REFERENCE_RESOURCE_STATUS`.
`verify:documentation` derives that list from the route registry and fails if
this paragraph falls behind it.
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
`review:a11y-manual -- --format-only`, which checks that every route record
keeps the template's fields, reviewed or still pending.
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
eligible-sample threshold and 28 days of production data exist.
@@ -166,7 +168,7 @@ Live release verification additionally requires `HOSTING_BASE_URL`.
## CI and evidence
The 27-gate registry is `config/ci/gates.json`; the Gitea workflow is
The 28-gate registry is `config/ci/gates.json`; the Gitea workflow is
`.gitea/workflows/quality-gates.yml`. It follows:
```text
+6 -6
View File
@@ -1,11 +1,11 @@
{
"schemaVersion": 1,
"owner": "frontend-platform",
"reason": "12-04: FE-GATE-003 runs the image resolve-signal type fixture and FE-GATE-010 runs check:adapter-inventory",
"gates": 27,
"commands": 93,
"commandReferences": 105,
"artifacts": 109,
"reason": "08-06: the signed manual accessibility review moves to release gate FE-GATE-028; merge gate FE-GATE-009 checks only the record format",
"gates": 28,
"commands": 94,
"commandReferences": 106,
"artifacts": 110,
"stages": 5,
"gateShapeSha256": "36d731b377e03518e744e2aea14f049bcf1286b6cd40ff24869a380db44d39b0"
"gateShapeSha256": "111e82fa1fd8341f8ee1f3d10d14365de382d83da5f8f9c5a1e3fcfecc5cafae"
}
+45 -35
View File
@@ -292,6 +292,15 @@
"script": "review:a11y-manual",
"expect": "pass"
},
{
"id": "check-a11y-manual-format",
"script": "review:a11y-manual",
"args": [
"--",
"--format-only"
],
"expect": "pass"
},
{
"id": "check-architecture",
"script": "check:architecture",
@@ -1109,55 +1118,37 @@
"id": "artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"path": "artifacts/tests/a11y-manual/APP_HOME.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-EXAMPLES-UI-md",
"path": "artifacts/tests/a11y-manual/EXAMPLES_UI.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-EXAMPLES-STATES-md",
"path": "artifacts/tests/a11y-manual/EXAMPLES_STATES.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-EXAMPLES-AUTH-md",
"path": "artifacts/tests/a11y-manual/EXAMPLES_AUTH.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-REFERENCE-RESOURCE-LIST-md",
"path": "artifacts/tests/a11y-manual/REFERENCE_RESOURCE_LIST.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"path": "artifacts/tests/a11y-manual/NOT_FOUND.md",
"schemaId": "markdown",
"production": "command-generated",
"producerCommandIds": [
"review-a11y-manual"
]
"production": "source-controlled"
},
{
"id": "artifact-artifacts-tests-a11y-manual-report-json",
@@ -1717,6 +1708,12 @@
"path": "artifacts/quality/gates/FE-GATE-027.txt",
"schemaId": "text",
"production": "runner-generated"
},
{
"id": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"path": "artifacts/quality/gates/FE-GATE-028.txt",
"schemaId": "text",
"production": "runner-generated"
}
],
"gates": [
@@ -1877,18 +1874,11 @@
"name": "accessibility",
"commandIds": [
"test-a11y",
"review-a11y-manual"
"check-a11y-manual-format"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-009-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-json",
"artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-UI-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-STATES-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-AUTH-md",
"artifact-artifacts-tests-a11y-manual-REFERENCE-RESOURCE-LIST-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
"artifact-artifacts-tests-a11y-json"
],
"retentionClassId": "merge-cycle"
},
@@ -2189,6 +2179,24 @@
"artifact-artifacts-release-deployment-admission-json"
],
"retentionClassId": "release-coherence"
},
{
"id": "FE-GATE-028",
"name": "manual-accessibility-review",
"commandIds": [
"review-a11y-manual"
],
"logArtifactId": "artifact-artifacts-quality-gates-FE-GATE-028-txt",
"evidenceArtifactIds": [
"artifact-artifacts-tests-a11y-manual-APP-HOME-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-UI-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-STATES-md",
"artifact-artifacts-tests-a11y-manual-EXAMPLES-AUTH-md",
"artifact-artifacts-tests-a11y-manual-REFERENCE-RESOURCE-LIST-md",
"artifact-artifacts-tests-a11y-manual-NOT-FOUND-md",
"artifact-artifacts-tests-a11y-manual-report-json"
],
"retentionClassId": "release-coherence"
}
],
"stages": [
@@ -2224,7 +2232,8 @@
"FE-GATE-015",
"FE-GATE-019",
"FE-GATE-026",
"FE-GATE-027"
"FE-GATE-027",
"FE-GATE-028"
]
},
{
@@ -2329,7 +2338,8 @@
"FE-GATE-012",
"FE-GATE-014",
"FE-GATE-019",
"FE-GATE-026"
"FE-GATE-026",
"FE-GATE-028"
],
"browserGateIds": [
"FE-GATE-026"
+6
View File
@@ -10,6 +10,12 @@ registry: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`,
blank identity/timestamp/signature fields, pending verdicts, mismatched release
IDs, or missing routes.
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
it is required once per release candidate, not on every merge. The merge gate
FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
and a record marked `reviewed` must be complete.
This list is not maintained by hand: `verify:documentation` compares it against
the installed route registry and fails when a registered route is absent. It
said six routes while ten were registered, which put the platform overview and
+1 -1
View File
@@ -1,6 +1,6 @@
# CI quality-gate orchestration
`config/ci/gates.json` is the executable registry for all 26 gates and the sole
`config/ci/gates.json` is the executable registry for all 28 gates and the sole
workflow model. `.gitea/workflows/quality-gates.yml` is generated from that
strict v2 contract; it is not an independent configuration authority. Update
the registry, run `corepack pnpm generate:ci-workflow`, and commit the generated
@@ -1103,8 +1103,11 @@ validate한다.
외부 배포 주소나 28일 field evidence가 없는 skeleton 개발 단계에서는 해당 gate가
실제 프로젝트가 채울 계약으로 남는다. 이를 fake data로 통과시키지 않는다.
현재 `FE-GATE-009`의 signed manual accessibility review는 merge gate다. 이
문서는 이를 production/field gate로 이동시키지 않는다.
signed manual accessibility review는 release gate `FE-GATE-028`이다
(`config/ci/gates.json`, 리뷰 08-06). 사람의 서명은 릴리스 후보 하나에 대해
하므로 merge마다 요구할 수 없다. merge gate `FE-GATE-009`는 자동 axe 검사와
기록 형식 검사(`review:a11y-manual -- --format-only`,
`scripts/lib/manual-a11y-evidence.ts`의 `validateManualA11yRecordFormat`)만 한다.
### 16.4 병렬화와 shard
+2 -2
View File
@@ -105,7 +105,7 @@ if (!architecture?.evidenceArtifactIds.some((id) => index.artifacts.get(id)?.pat
}
const expectedGateIds = Array.from(
{ length: 27 },
{ length: 28 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
const passingResults: Record<string, GateResult> = Object.fromEntries(
@@ -168,4 +168,4 @@ if (failures.length > 0) {
process.stderr.write(`CI contract failed:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write("CI contract: 27 gates, strict v2 graph and generated workflow model PASS\n");
process.stdout.write("CI contract: 28 gates, strict v2 graph and generated workflow model PASS\n");
+3 -3
View File
@@ -790,11 +790,11 @@ function validateContractSemantics(
}
const expectedGateIds = Array.from(
{ length: 27 },
{ length: 28 },
(_, index) => `FE-GATE-${String(index + 1).padStart(3, "0")}`,
);
if (JSON.stringify(contract.gates.map(({ id }) => id)) !== JSON.stringify(expectedGateIds)) {
issue("gate registry must contain FE-GATE-001..027 in canonical order");
issue("gate registry must contain FE-GATE-001..028 in canonical order");
}
const expectedStages: ReadonlyArray<readonly [string, string, readonly string[], readonly string[]]> = [
["merge", "MERGE_READY", [], PROMOTION_FORMULA.MERGE_READY],
@@ -864,7 +864,7 @@ function validateContractSemantics(
}
const expectedJobOwnership: Readonly<Record<string, readonly string[]>> = {
merge_gate: ["FE-GATE-001", "FE-GATE-002", "FE-GATE-003", "FE-GATE-004", "FE-GATE-005", "FE-GATE-006", "FE-GATE-007", "FE-GATE-008", "FE-GATE-009", "FE-GATE-010", "FE-GATE-011", "FE-GATE-013", "FE-GATE-020"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-019", "FE-GATE-026"],
release_gate: ["FE-GATE-012", "FE-GATE-014", "FE-GATE-019", "FE-GATE-026", "FE-GATE-028"],
immutable_build: ["FE-GATE-015", "FE-GATE-027"],
vulnerability_provider: [],
provenance_provider: [],
+1 -1
View File
@@ -4,7 +4,7 @@ export const ciContractReportSchema = z
.object({
schemaVersion: z.literal(2),
nodeVersion: z.string().regex(/^\d+\.\d+\.\d+$/u),
gateCount: z.literal(27),
gateCount: z.literal(28),
commandDefinitionCount: z.number().int().positive(),
commandReferenceCount: z.number().int().positive(),
artifactCount: z.number().int().positive(),
+46 -3
View File
@@ -15,8 +15,20 @@ const REVIEW_FIELDS = Object.freeze([
"Screen reader",
]);
export function validateManualA11yEvidence(content: string) {
const fields = Object.fromEntries(
const IDENTITY_FIELDS = Object.freeze([
"Status",
"Route ID",
"Release ID",
"Reviewer",
"Reviewed at",
"Signature",
"Attestation",
]);
const NOT_APPLICABLE = /^not-applicable \(.+\)$/;
function parseRecordFields(content: string): Record<string, string> {
return Object.fromEntries(
content
.split(/\r?\n/)
.map((line) => /^([^:]+):\s*(.*)$/.exec(line))
@@ -26,6 +38,37 @@ export function validateManualA11yEvidence(content: string) {
match[2].trim(),
]),
);
}
/**
* 08-06. The merge-stage check: the record for `routeId` keeps the template's
* fields and vocabulary, whether or not a human has reviewed it yet. A record
* that claims `reviewed` must also be complete. Returns the offending fields.
*/
export function validateManualA11yRecordFormat(content: string, routeId: string): string[] {
const fields = parseRecordFields(content);
const failures = [...IDENTITY_FIELDS, ...REVIEW_FIELDS].filter(
(field) => !(field in fields),
);
if (fields.Status !== undefined && !["pending-manual-review", "reviewed"].includes(fields.Status)) {
failures.push("Status");
}
if (fields["Route ID"] !== undefined && fields["Route ID"] !== routeId) failures.push("Route ID");
if (fields.Attestation !== undefined && !["pending", "accepted"].includes(fields.Attestation)) {
failures.push("Attestation");
}
for (const field of REVIEW_FIELDS) {
const verdict = fields[field];
if (verdict !== undefined && verdict !== "pass" && verdict !== "pending" && !NOT_APPLICABLE.test(verdict)) {
failures.push(field);
}
}
if (fields.Status === "reviewed") failures.push(...validateManualA11yEvidence(content).failures);
return [...new Set(failures)];
}
export function validateManualA11yEvidence(content: string) {
const fields = parseRecordFields(content);
const failures: string[] = [];
if (fields.Status !== "reviewed") failures.push("Status");
if (!fields["Route ID"]) failures.push("Route ID");
@@ -44,7 +87,7 @@ export function validateManualA11yEvidence(content: string) {
const result = fields[field];
if (
result !== "pass" &&
!/^not-applicable \(.+\)$/.test(result ?? "")
!NOT_APPLICABLE.test(result ?? "")
) {
failures.push(field);
}
+3
View File
@@ -23,6 +23,9 @@ export const PROMOTION_FORMULA = Object.freeze({
// FE-GATE-027. A candidate is only release-ready once it has been admitted
// to a named environment; coherence alone never proved it belonged there.
"FE-GATE-027",
// FE-GATE-028 (08-06). The signed human accessibility review belongs to a
// release candidate, so it gates release; merge checks the record format.
"FE-GATE-028",
]),
PROD_PROMOTION_READY: Object.freeze([
"FE-GATE-016",
+22
View File
@@ -4,6 +4,7 @@ import { manualA11yReportArtifactSchema } from "./contracts/release-artifacts.ts
import {
MANUAL_A11Y_ROUTE_IDS,
validateManualA11yEvidence,
validateManualA11yRecordFormat,
} from "./lib/manual-a11y-evidence.ts";
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
@@ -17,6 +18,27 @@ type ManualA11yResult = Readonly<{
passed: boolean;
}>;
// 08-06: the signed review is a release-stage gate (FE-GATE-028). The merge
// stage (FE-GATE-009) runs `--format-only`: every route has a record in the
// template's shape, reviewed or not.
if (process.argv.includes("--format-only")) {
const failures: string[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
const record = await readFile(path, "utf8").catch(() => null);
const invalid = record === null ? ["missing record"] : validateManualA11yRecordFormat(record, routeId);
if (invalid.length > 0) failures.push(`${path}: ${invalid.join(", ")}`);
}
if (failures.length > 0) {
process.stderr.write(`Manual accessibility record format is invalid:\n${failures.join("\n")}\n`);
process.exit(1);
}
process.stdout.write(
`Manual accessibility record format: PASS (${MANUAL_A11Y_ROUTE_IDS.length} routes; signed review runs in FE-GATE-028)\n`,
);
process.exit(0);
}
const results: ManualA11yResult[] = [];
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const path = `artifacts/tests/a11y-manual/${routeId}.md`;
@@ -96,6 +96,7 @@ jobs:
- { gate: FE-GATE-014, name: config-compatibility, browser: false }
- { gate: FE-GATE-019, name: hosting-header, browser: false }
- { gate: FE-GATE-026, name: lab-performance, browser: true }
- { gate: FE-GATE-028, name: manual-accessibility-review, browser: false }
steps:
- uses: https://github.com/actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
with:
+20 -4
View File
@@ -189,22 +189,38 @@ describe("CI gate contract", () => {
const index = indexCiGateContract(contract);
expect(contract.schemaVersion).toBe(2);
expect(contract.gates.map(({ id }) => id)).toEqual(
Array.from({ length: 27 }, (_, index) =>
Array.from({ length: 28 }, (_, index) =>
`FE-GATE-${String(index + 1).padStart(3, "0")}`,
),
);
expect(contract.jobs).toHaveLength(9);
expect(contract.commands).toHaveLength(93);
expect(contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0)).toBe(105);
expect(contract.commands).toHaveLength(94);
expect(contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0)).toBe(106);
expect(contract.commands.filter(({ expect }) => expect === "fail")).toHaveLength(31);
expect(contract.gates.reduce((total, gate) => total + gate.evidenceArtifactIds.length, 0)).toBe(88);
expect(contract.artifacts).toHaveLength(109);
expect(contract.artifacts).toHaveLength(110);
expect(contract.stages).toHaveLength(5);
expect(contract.retention.classes).toHaveLength(5);
expect(index.gates.get("FE-GATE-015")?.commandIds).toHaveLength(2);
expect(index.gates.get("FE-GATE-020")?.name).toBe("removability");
});
it("runs the signed manual accessibility review at release, not merge (08-06)", async () => {
const contract = await loadCiGateContract(process.cwd());
const index = indexCiGateContract(contract);
const scriptsOf = (gateId: string) =>
(index.gates.get(gateId)?.commandIds ?? []).map((id) => {
const command = index.commands.get(id);
return [command?.script, ...(command?.args ?? [])].join(" ");
});
const stageOf = (gateId: string) =>
contract.stages.find(({ gateIds }) => gateIds.includes(gateId))?.id;
expect(scriptsOf("FE-GATE-009")).toEqual(["test:a11y", "review:a11y-manual -- --format-only"]);
expect(scriptsOf("FE-GATE-028")).toEqual(["review:a11y-manual"]);
expect(stageOf("FE-GATE-009")).toBe("merge");
expect(stageOf("FE-GATE-028")).toBe("release");
});
it("keeps the action registry recursively immutable and resolves only known actions", () => {
expect(Object.isFrozen(CI_ACTION_REGISTRY)).toBe(true);
expect(Object.values(CI_ACTION_REGISTRY).every((action) => Object.isFrozen(action))).toBe(true);
+38
View File
@@ -1,8 +1,11 @@
import { describe, expect, it } from "vitest";
import { readFileSync } from "node:fs";
import {
MANUAL_A11Y_ROUTE_IDS,
validateManualA11yEvidence,
validateManualA11yRecordFormat,
} from "../../scripts/lib/manual-a11y-evidence.ts";
import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.ts";
@@ -64,4 +67,39 @@ describe("manual accessibility evidence", () => {
passed: false,
});
});
// 08-06: the merge stage checks only that each record keeps the template's
// shape; the signed review itself is a release-stage gate (FE-GATE-028).
describe("record format", () => {
const pending = reviewed
.replace("Status: reviewed", "Status: pending-manual-review")
.replace("Release ID: release-1", "Release ID:")
.replace("Reviewer: reviewer@example.test", "Reviewer:")
.replace("Reviewed at: 2026-07-25T12:00:00Z", "Reviewed at:")
.replace("Signature: review-record-1", "Signature:")
.replace("Attestation: accepted", "Attestation: pending")
.replace("M1 Keyboard: pass", "M1 Keyboard: pending");
it("accepts a pending template and a signed record", () => {
expect(validateManualA11yRecordFormat(pending, "APP_HOME")).toEqual([]);
expect(validateManualA11yRecordFormat(reviewed, "APP_HOME")).toEqual([]);
});
it("accepts every checked-in route record", () => {
for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
const record = readFileSync(`artifacts/tests/a11y-manual/${routeId}.md`, "utf8");
expect(validateManualA11yRecordFormat(record, routeId), routeId).toEqual([]);
}
});
it.each([
["a missing field", pending.replace("Signature:\n", ""), "APP_HOME", "Signature"],
["an unknown status", pending.replace("Status: pending-manual-review", "Status: done"), "APP_HOME", "Status"],
["an unknown verdict", pending.replace("M1 Keyboard: pending", "M1 Keyboard: ok"), "APP_HOME", "M1 Keyboard"],
["another route's record", pending, "NOT_FOUND", "Route ID"],
["a reviewed record that is not complete", reviewed.replace("Signature: review-record-1", "Signature:"), "APP_HOME", "Signature"],
])("rejects %s", (_name, record, routeId, field) => {
expect(validateManualA11yRecordFormat(record, routeId)).toContain(field);
});
});
});